Skip to content

ParticleIntegrator: Function Overview

Jump to bottom Edit New page
Julian edited this page Sep 1, 2014 · 9 revisions

This list of functions should give an overview of what each function in the Particle Integrator code is doing and which arguments they take and return.

Contents

Where to Find the Most Important Code

  1. main is doing a lot of the file handling and calls the integrator functions.

  2. calc_accel is where all the physics happens.

  3. RungeKutta4 and RungeKutta76 are the integration functions and contain all the calls of calc_accel. They also contain most of the saving calls (printpdata), only a few things are saved from main.

  4. convert_results_into_binary does what the name suggest and converts the finished results into a binary file to send it back to the Constellation server.

  5. read_configuration reads all the configuration. If you add a value to the configuration options, you have to make changes here, in the handler (static) and probably print it out at the beginning of the main function.

Functions

main

Returns: int

  • 0: Success
  • 1: Input error
  • 2: Output or processing error

Arguments:

  • int argc, char *argv[]: Input arguments via command line.

What it does:

  • Print some basic information about the version and platform
  • Check for command line input arguments
  • Read configuration
  • Read particles from input file
  • Print configuration and particle information
  • Update progress.txt with a progress value (between 0 and 1)
  • Check for particles that have already been coomputed
  • Loop over particles
  • Check if particle has already been completed
  • Check if particle has already been processed but is incomplete
  • Set initial state
  • Create output file
  • Integrate particle
  • Write the particle number to the already-done file and update progress.txt
  • Note if the particle is an encounter particle (if enabled)
  • Return computation time (if enabled)
  • Convert output to binary (if enabled)
  • Deallocate arrays

Internal function calls:

  • printinfo()
  • read_configuration(&config_data)
  • calc_pInfo(&config_data)
  • particle_in_file(p, already_done_path)
  • particle_incomplete(particle_path, nstate)
  • printpdata(init, nstate)
  • RungeKutta4(&config_data, nstate, statefile) or RungeKutta76(&config_data, nstate, statefile)
  • convert_results_into_binary(&config_data, particles_count, multiplication_factor, already_done_path, encounter_path)

In file: SourceCode.c

particle_in_file

Returns: bool

  • true: Particle is in file
  • false: Particle is not in file

Arguments:

  • int p: Particle number
  • char path[]: File path to check for particle

What it does:

  • Checks if the particle number appears somewhere in the given file.

In file: SourceCode.c

particle_incomplete

Returns: bool

  • true: Particle computation is incomplete
  • false: Particle computation is not imcomplete

Arguments:

  • char particle_path[]: Particle path to check
  • SpiceDouble *nstate: Used to return the latest state if necessary

What it does:

  • Checks if the particle has already been processed but is incomplete (i.e. if there is more than one line in the result file)
  • Returns the newest state from the file as *nstate
  • Removes the newest state from the output file (because it will be rewritten before the integration starts)
  • Restarts the integration if the file can't be read

In file: SourceCode.c

handler (static)

Returns: int

  • 0: Unknown section/name, error
  • 1: Success

Arguments:

  • void* user: configuration struct
  • const char* section: Ini file section
  • const char* name: Ini variable name
  • const char* value: Return value (value of that variable)

What it does:

  • Part of the inih library reading the configuration.ini file.
  • This function checks a pair of a section and variable name and returns the value that this variable has in the file.

In file: SourceCode.c

read_configuration

Returns: int

  • 0: Success
  • 1: Out of memory
  • 2: Error (specific error will be printed, probably a missing value)

Arguments:

  • configuration_values *config_data: Configuration data struct

What it does:

  • Set default values for configuration values
  • Allocate memory for char arrays
  • Call the configuration parser
  • Convert every returned value to a useful format and put it into config_data
  • Free memory

In file: SourceCode.c

convert_results_into_binary

Returns: int

  • 0: Success
  • 1: Problem with the binary file creation
  • 2: Out of memory or a problem with the particle file

Arguments:

  • configuration_values *config_data: Configuration data
  • int particles_count: Number of particles
  • double *multiplication_factor: Multiplication factor of each particle
  • char already_done_path[]: Path of the file containing the list of particles that were already done
  • char encounter_path[]: Path of the file containing the list of particles that had encounters

What it does:

  • Allocate memory for result array
  • Set the header for the result file
  • Read all the particles and save the in the results array
  • Check if the particle should not be saved because it doesn't represent an encounter (if enabled)
  • Save the result array as a binary file and delete the text files
  • Free memory

In file: SourceCode.c

printinfo

Returns: void (nothing)

Arguments: none

What it does:

  • Print the name of the application
  • Print the version number
  • Print the platform for which the application was compiled
  • For debug builds: Print the CMake flags

In file: SourceCode.c

RungeKutta4

Returns: int

  • 0: Success
  • 1: Out of memory/no Sun configured.

Arguments:

  • configuration_values *config_data: All configuration values
  • SpiceDouble *nstate: State vector to begin with
  • FILE *statefile: File to print the output into

What it does:

  • Allocate memory for the body states at three different times
  • Until the final time is reached, repeat:
  • Initialize the initial state vectors of bodies and the particle
  • Do first integration step
  • Set dynamic step size
  • Start saving if it's time
  • Perform step saving rate optimization (if enabled)
  • End integration on time (reduce time step size) (if enabled)
  • Get the body positions with spice
  • Do the second to fourth integration step
  • Update the resulting state vector of the particle
  • Save the state to the file if appropriate
  • Print last state to the file
  • Free memory

Internal function calls:

  • get_body_state(config_data, j, &nstate[6], &body_end)
  • calc_accel(config_data, dir_SSB, &body_pre, k_acc_1, initVel, 0.0)
  • calc_save_factor(config_data, dir_SSB, &body_pre, k_acc_1, initVel, 0.0)
  • get_body_state(config_data, j, &nextInitTime, &body_end)
  • calc_accel(config_data, dir_SSB, &body_mid, k_acc_2, initVel, dt2)
  • calc_accel(config_data, dir_SSB, &body_mid, k_acc_3, initVel, dt2)
  • calc_accel(config_data, dir_SSB, &body_end, k_acc_4, initVel, dt)
  • printpdata(statefile, nstate)

In file: Integrators/RungeKutta4.h

RungeKutta76

Returns: int

  • 0: Success
  • 1: Out of memory/no Sun configured.

Arguments:

  • configuration_values *config_data: All configuration values
  • SpiceDouble *nstate: State vector to begin with
  • FILE *statefile: File to print the output into

What it does:

  • Allocate memory for the body states at 9 different times
  • Get initial body states
  • Allocate memory for the interpolation of the body states
  • Until the final time is reached, repeat:
  • Initialize the initial state vectors of bodies and the particle
  • Do first integration step
  • Set dynamic step size
  • Start saving if it's time
  • Perform step saving rate optimization (if enabled)
  • Do until the error is low enough
  •    End integration on time (reduce time step size) (if enabled)
  •    Calculate the intermediate time intervals
  •    Interpolate and get body positions for all necessary times
  •    Do the second to ninth integration step
  •    Calculate the error of the integration step
  • Update the resulting state vector of the particle
  • Save the state to the file if appropriate
  • Print last state to the file
  • Free memory

The similarity of this layout to the layout of the RK4 method is intentional and reduces the probability of introducing bugs in either of them during changes.

Internal function calls:

  • get_body_state(config_data, j, &nstate[6], &body[8])
  • interp_body_states_malloc(config_data, &body_c)
  • calc_accel(config_data, dir_SSB, &body[1], f[0], initVel, 0.)
  • calc_save_factor(config_data, dir_SSB, &body[1], f[0], initVel, 0.)
  • precompute_dtime_powers(config_data, &dtp, dtime)
  • get_body_state(config_data, j, &time[8], &body[8])
  • interp_body_states(config_data, &body, &body_c, dtime, &dtp, h, j)
  • get_body_state(config_data, j, &time[m], &body[m])
  • calc_accel(config_data, dir_SSB, &body[2], f[1], initVel, dtime[2] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[3], f[2], initVel, dtime[3] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[4], f[3], initVel, dtime[4] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[5], f[4], initVel, dtime[5] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[6], f[5], initVel, dtime[6] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[7], f[6], initVel, dtime[7] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[8], f[7], initVel, dtime[8] - dtime[1])
  • calc_accel(config_data, dir_SSB, &body[8], f[8], initVel, dtime[8] - dtime[1])
  • printpdata(statefile, nstate)
  • interp_body_states_free(config_data, &body_c)

In file: Integrators/RungeKutta76.h

get_body_state

Returns: void (nothing)

Arguments:

  • configuration_values *config_data: All configuration values
  • int body_index: Index of the body in the list of bodies given in the configuration
  • SpiceDouble *time: Time for which the state vector is supposed to be returned
  • SpiceDouble **body_state_vector[]: Array pointer to place the results in

What it does: This function decides, based on configuration settings, whether it has to return:

  • [0 0 0] as the position vector of the SSB
  • [0 0 0 0 0 0] as the position and velocity vector of the SSB
  • The position vector of the body through spice (spkezp_c)
  • The position and velocity vector of the body through spice (spkezr_c)

Function calls:

  • spkezp_c(config_data->body_int[body_index], *time, "ECLIPJ2000", "NONE", 0, (*body_state_vector)[body_index], &lt)
  • spkezr_c(config_data->body_char[body_index], *time, "ECLIPJ2000", "NONE", "0", (*body_state_vector)[body_index], &lt)

In file: Integrators/IntegEnv.h

calc_accel

Returns: void (nothing)

Arguments:

  • configuration_values *config_data: All configuration values
  • SpiceDouble dir_SSB[]: The position vector of the solar system barycenter from the position of the particle
  • SpiceDouble **body_state[]: The array containing all the body states
  • SpiceDouble *accel: Vector pointer to return the acceleration in
  • SpiceDouble *Vel: Velocity vector of the particle relative to the SSB (actually, relative to the Sun would be more accurate)
  • SpiceDouble dt: Time difference since the *Vel value was calculated for some interpolation

What it does: This function returns the acceleration of the particle under the circumstances given through the input arguments:

  • Acceleration based on Newtonian gravity
  • Is it an encounter?
  • For the Sun only:
  • Estimate a current speed relative to the Sun (to the SSB, see above)
  • Calculate acceleration through radiation pressure, Poynting-Robertson drag and solar wind drag
  • Calculate acceleration through the effects of general relativity

In file: Integrators/IntegEnv.h

calc_save_factor

Returns: int

  • 0: Success
  • 1: No Sun

Arguments: See calc_accel above.

What it does: This function calculates the acceleration of the particle under the circumstances given through the input arguments, just like calc_accel does. However, it does this only for the Sun. Based on the difference between the result and the output from calc_accel, it determines the influence that planets have on the current acceleration of the particle. If this influence is significant, e_save_max is set to a value greater than 1 to trigger an increase in the number of steps that are saved. If the influence is very small, e_save_max stays at a value close to 1.

This makes sure that more steps are saved if a planet is close to the particle and has a significant influence on the orbit of the particle. This helps if the data processing uses kepler orbits for interpolation, in which planetary perturbations are not represented at all and therefore interpolated badly.

The return value is config_data->step_multiplier.

In file: Integrators/IntegEnv.h

printpdata

Returns: int

  • 0: Success
  • 1: Result is not a number and will not be saved

Arguments:

  • FILE *statefile: File to save the result in
  • SpiceDouble *nstate: State to save

What it does:

  • Check if any part of the state is not a number.
  • Print the state to the file if that's not the case.

The check is needed to make sure that any external tool can read the state file afterwards even if it doesn't handle NANs very well. An error message is printed in such a case.

In file: Integrators/IntegEnv.h

calc_pInfo

Returns: int

  • 0: Success

Arguments:

  • configuration_values *config_data: All the configuration values

What it does: This function calculates the part of the Poynting-Robertson drag equation that is constant for one particle across time to make sure that this is only calculated once.

It also calculates the beta value for the particle.

Return values: config_data->beta, config_data->betaGM, config_data->particle_radius

In file: Integrators/IntegEnv.h

interp_body_states_malloc

Returns: int

  • 0: Success

Arguments:

  • configuration_values *config_data: All the configuration values
  • SpiceDouble **(*body_c)[6]: Body state coefficient vector

What it does: This function figures out how large the body state interpolation array has to be (based on the interpoltion order that was chosen) and allocates a corresponding amount of memory.

In file: Integrators/IntegEnv.h

interp_body_states_free

This frees up all the memory that interp_body_states_malloc has allocated.

interp_body_states

Returns: int

  • 0: Success
  • 2: No interpolation performed (either none was asked for or the order is not supported)

Arguments:

  • configuration_values *config_data: All the configuration values
  • SpiceDouble **(*body)[9]: The body states, of which some have to be filled and others are taken as input
  • SpiceDouble **(*body_c)[6]: The body interpolation coefficient pointer(s) to fill
  • SpiceDouble dtime[9]: The time intervals to use for the interpolation
  • dtimepowers *dtp: Values from dtime, with a few power computations done to them (see function below)
  • SpiceDouble h: Total time difference of this interpolation step
  • int j: body index

What it does: This function performs a second order or fifth order interpolation of the given body states. The formulae are a straightforward written-out linear equation solver. The sigma (sig) variables store values that need to be computed twice to save time.

In file: Integrators/IntegEnv.h

precompute_dtime_powers

Returns: void (nothing)

Arguments:

  • configuration_values *config_data: All the configuration values
  • dtimepowers *dtp: Pointer to return the values in
  • SpiceDouble dtime[9]: Time intervals to work with

What it does: This function computes a few powers to dtime[1], dtime[8] and the difference between these values. These are needed in the equations of the fifth-order interpolation.

In file: Integrators/IntegEnv.h

Add a custom footer

Particle Integrator

Building on

Usage

Code

ParticleAnalyser

Building on

Usage

Clone this wiki locally