


1. Compiling

The program uses only standard C++ libraries, so the provided Makefile under src/ should do via

make leo_targeting

In addition

make clean

can be used to delete all object files.


2. Running

The program is ran from the commandline with a configuration file name as argument as e.g.

./leo_targeting myconfig.cfg

The output will be either to console or to a filename specified in the configuration tile. The configuration file needs to contain a program to be executed in terms of the setup of a state, instructions for how long to simulate it, what changes to make to it, what quantities to list on-screen and what quantities to plot into file. There is no graphical output provided, instead any external plotting (or math analysis) tool (such as e.g. gnuplot) can be used to visualize results. A couple of sample config files is provided in the config/ subfolder.

3. Config file format

The config file needs to contain both single word and two word instructions. Single keywords delimit modes and blocks, two keywords form a key-value pair that sets a parameter.

Valid mode-setting keywords are

* input:  begins the declarations of the simulated situation
* output:  begins the declaration of what information should be outputted on-screen or to file
* end: signals the end of the config file

Valid block-delimiting keywords are

* config: sets general simulation parameters
* position: specifies an initial spacecraft state as lat/lon/alt and heading/horizontal speed/vertical speed
* state_vector: specifies an initial spacecraft state as three component position and three component velocity vector
* burn_peg7: specifies an externally targeted burn with prograde, radial and normal Delta v components 
* burn_peg4: specifies a targeted burn with PEG-4 targeting parameters (triggers a fit procedure)
* burn_low_thrust: specifies a burn scheme which requires periodic ignition across many orbits such as used for ion thrusters
* burn_lambert: specifies a two-burn targeted rendezvous sequence (triggers a fit procedure and requires an orbital target definition)
* landing_site: sets the geographical position of a landing site for de-orbit targeting
* launch_site: sets the geographcal position of the launch site for Shuttle OPS-1 angle definition reference
* celestial_body: allows to define a gravitating body through an accompanying ephemeris file
* target_state_vector: specifies the initial state of an orbital rendezvous target as position and velocity vector
* target_position: specifies the initial state of an orbital rendezvous target as lat/lon/alt and  and heading/horizontal speed/vertical speed
* plot_2d: defines a 2d output format ready to be plotted
* plot_3d: defines a 3d output format ready to be plotted
* spacecraft: defines the computation-relevant properties of a spacecraft and its engine
* list: defines at which points the simulation should output part of its internal state on-screen
 
Out of these, only plot_2d, plot3d and list are part of the output mode, all others belong to the input mode.


3.1 Config settings

The config block supports the following keys and values (the first option is the default if there is one, if there is a number indicated it is the default value of a numerical setting):

* units: [SI/imperial] sets whether input and output should be in meters, kilometers or m/s or in feet, nautical miles and ft/s
* time format: [plain/MET] sets whether times on-screen and in the mission file are given in seconds or in the Shuttle mission elapsed time format ddd/hh:mm:ss.s
* gravity_model: [spherical/J2/J3] sets whether Earth gravity is assumed to be a simple spherical point mass or contains the J2 deformation or the J2 and J3 deformation terms
* earth_model: [spherical/IERS] sets whether Earth shape is assumed to be a perfect sphere or the IERS reference ellipsoid (this affects above ground altitude calculations)
* burn_model: [impulse/constant/rocket_engine] sets whether orbital maneuvering burns are instantaneous velocity changes at the specified time (impulse approximation), finite-duration burns with constant acceleration or a simulation of a rocket engine using propellant (this needs a spacecraft defined).
* fit_max_iterations: [100] sets how many iterations fits will try before giving up
* fit: [silent/verbose]: whether the fit will output the results of each iteration or just the final result - note that internal quantities displayed are always in SI units
* max_time:[8000.0] time to which the simulation will run if it does not run out of plot points first
* timestep: [0.01] the timestep the simulation uses to compute trajectories
* plot2d_resolution: [100] the number of timesteps the plot will skip before generating a point - with a default timestep of 0.01 s, the default value means that a quantity will be plotted every second. With 5000 max. points in the plot, this means 5000 seconds of simulation, changing the parameter to 200 allows instead 10.000 seconds.
* plot3d_resolution: [100] as above, just for the 3d plot

3.2 Position settings

The position block is used for quickly setting up an orbital situation - it defines the initial spacecraft position in earth-relative coordinates. The same keys are valid for the position of an orbital target. The supported keys are:

* lat: initial latitude of the spacecraft in degrees
* lon: initial longitude of the spacecraft in degrees
* alt: initial altitude of the spacecraft (in ft or m according to the chosen unit system)
* heading: initial heading of the spacecraft in degrees
* vtot: initial horizontal speed in m/s or ft/s
* vup: initial vertical speed in m/s or ft/s

3.3 State vector settings

The state vector block is used alternatively to the position block to set up an orbital situation in inertial coordinates. The same keys are valid to describe the state of an orbital rendezvous target. The inertial coordinate system is always chosen such that the coordinate center is at the center of Earth and initially the (lat, lon) = (0,0) points towards the x-axis and the z-axis points towards the north pole (this is the choice made by the  JSBSim package as well such that state vectors from simulators such as Flightgear can be directly exported). Due to the rotation of Earth, this relation changes over time. The keys are:

* x(y,z): Position components of the state vector (in m or ft according to selected unit system)
* vx (vy, vz): Velocity components of the state vector (in m/s or ft/s according to selected unit system)
* MET: mission-elapsed time at the beginning of the simulation (the simulated evolution of time will be added to this value) - either in seconds or as MET string according to the chosen unit system

3.4 Spacecraft settings

The spacecraft section can be used to define the capabilities of the simulated spacecraft. This can be done by either specifying an acceleration or enough information to evaluate the rocket equation, i.e. thrust, dry mass, propellant mass and specific impulse of the rocket motor. The supported keys are

* acceleration: the acceleration of the craft - based on chosen units either m/s^2 or ft/s^2 (if an acceleration is defined, the parameters below should not be specified)
* mass: total mass of the spacecraft (dry plus propellant)
* mass_dry: mass of the spacecraft without propellant
* propellant_mass: mass of the propellant (only two of the last parameters need to be given)
* thrust: thrust of the rocket engine, either in N or lb dependent on unit system
* isp: specific impulse of the rocket engine in s

Defining a detailed spacecraft with rocket engine always forces a listing of the parameters to check the resulting acceleration.


3.5 PEG-7 burn settings

A PEG-7 (where PEG stands for 'powered explict guidance') burn is not targeted at a certain point in space but has to fulfill externally given velocity targets - hence it does not require any fit procedure. The keys for such a burn are

* time: the time (in seconds after simulation start) at which the burn should take place (for constant acceleration burns this is ignition time and the burn will run a finite time after that)
* tig: alternatively, ignition time in MET format
* dv_prograde (or dx): the prograde velocity change (in m/s or ft/s)
* dv_normal (or dy): the normal velocity change (in m/s or ft/s)
* dv_radial (or dz): the radial velocity change (in m/s or ft/s)
* name: a designation for the burn that will used in information written to the console

3.6 PEG-4 burn settings

A PEG-4 burn is targeted at a specific point in space and hence always requires a fit procedure. In addition, the simulation allows to optimize the burn to minimize radial Delta v and burn duration - this goes beyond the original PEG-4 scheme. The keys are:

* time: the time (in seconds after simulation start) at which the burn should take place (for constant acceleration burns this is ignition time and the burn will run a finite time after that)
* tig: alternatively, ignition time in MET format
* H: altitude above the surface of the targeted point - this can be in miles or feet or alternatively in m or km if SI units are chosen
* thetaT: the angle along the trajectory to the targeted point - the exact definition depends on the set OPS, in OPS 1 this refers to the launch site (which has to be set), in OPS 3 (the default) it is from the ignition point of the burn
* c1 and c2: vertical speed constraints at the targeting point - the vertical velocity v_vert must fulfill v_vert = c2 + v_horiz * c1. This requires c2 to be in units of ft or meters according to the chosen units.
* REI: if a landing site is defined, optionally REI (range from entry interface) in miles or km can be specified, the fit will then be allowed to modify ignition time to target this rage to the landing site
* ops: [3/1] the operational sequence in the Shuttle avionics which determines the theta angle definition - valid values are 1 and 3
* optimize: [time/theta]: for apsis-placing burns where c1 = c2 = 0, using this key instructs the fit to allow modifications of either ignition time or theta to minimize burn time 
* name: a designation for the burn that will used in information written to the console

3.7 Low thrust burn settings

A low thrust burn definition takes care of situations where orbital parameters can not be changed quickly and maneuvering times extend over many orbital periods. In this situation, one would typically ignite the engine every time a certain portion of the orbit is reached, i.e. a condition is met. This condition can be specified by a normalized target vector and a tolerance - whenever the normalized velocity dotted into the target vector results in a value larger than the tolerance, the engine is ignited.

The keys to define a low thrust burn are

* time: the time (in seconds after simulation start) at which the burn should take place (for constant acceleration burns this is ignition time and the burn will run a finite time after that)
* tig: alternatively, ignition time in MET format
* name: a designator for the burn to identify it in the log output
* dv_prograde (or dx): the prograde velocity change (in m/s or ft/s)
* dv_normal (or dy): the normal velocity change (in m/s or ft/s)
* dv_radial (or dz): the radial velocity change (in m/s or ft/s)
* tvec_x: x-component of the ignition condition target vector
* tvec_y: y-component of the ignition condition target vector
* tvec_z: z-component of the ignition condition target vector
* tolerance: minimal dot product between prograde vector and target vector that still leads to ignition
* trig_in_plane [disable/enable]: whether the condition target vector is forced to be in the current orbital plane or not

3.8 Lambert burn settings

A Lambert burn sequence computes a solution to intercept an orbital target - such a target needs to be defined for a Lambert burn definition to be accepted. The sequence always consists of a position intercept burn at time t1 and an (optional) velocity match burn at intercept time t2 (for extended burns, the actual ignition time of the obtained burn will be different from the intercept time to compensate for finite-time effects). Optionally, an offset to the target can be specified (one might not want to crash right into the target).

The keys to define a Lambert burn sequence are:

* t1: the ignition time of the position intercept burn
* t2: the time at which the intercept location is reached
* name: an optional designation for the burn to identify it in the log output
* offset_x: offset of the targeting point to the target position in prograde direction
* offset_y: offset of the targeting point to the target position in normal direction
* offset_z: offset of the targeting point to the target position in radial direction
* disable [auto_burn2/y_fit]: disable automatically executing the velocity-matching burn and only print its parameters and disable trying to match the orbital plane during the burn

3.9 Landing site settings

A landing site is an Earth co-moving coordinate position relative to which the range from entry interface is evaluated. Such a site is only needed when optimized burns are done, and unless the burn is REI-targeting, the site coordinates are not used. The keys are

* lat: the site latitude
* lon: the site longitude
* name: a designation which identifies the site in on-screen messages


The site name can be set to a three letter code, if it is recognized, the coordinates are chosen automatically. Currently recognized sites are KSC (Kennedy Space Center), VBG (Vandanberg Air Force Base) and EDW (Edwards Air Force Base).

3.10 Launch site settings

A launch site is an Earth co-moving coordinate position relative to which the theta-angle in OPS 1 is determined. The keys are:

* lat: the site latitude
* lon: the site longitude
* name: a designation which identifies the site in on-screen messages

The site name can be set to a three letter code, if it is recognized, the coordinates are chosen automatically. Currently recognized sites are KSC (Kennedy Space Center), VBG (Vandanberg Air Force Base) and EDW (Edwards Air Force Base).

3.11 Celestial body settings

A celestial body is an additional gravitating influence acting from a position which is at each time defined via an ephemeris file. The keys to be set in the config file are:

* name: name of the body
* ephemeris: the path to the ephemeris file
* GM: the standard gravitational parameter (product of mass and gravitational constant) for the body

The ephemeris file format is a table with four columns and no comments allowed. The columns need to contain the location in the sky in geocentric angles as follows:

* first column: time since simulation start
* second column: right ascension of the body, converted into degrees
* third column: declination of the body in degrees
* fourth column: distance to the body from the center of Earth in kilometers

Data for such geocentric ephemerides can be obtained for many solar system bodies from astronomy websites.

3.12 List settings

Lists are information tables written to the console. They can be requested at three different points of the simulation - for the initial and final state and for the entry interface.

* position: [initial, final, entry_interface] lists Earth-relative coordinates and the course-distance information to a landing site if defined
* orbital:  [initial, final, entry_interface] lists the six orbital elements in addition to some more useful information
* state_vactor:  [initial, final, entry_interface] lists the raw state vector

3.13 Plot settings

A plot definition means that the requested data (up to 5000 points) is dumped to a file. Each n timesteps, the qualities are pulled out of the simulation and stored. A plot can be 2d or 3d (both can be used at the same time) is defined as

* file: the filename to be used
* x: [<parameter>] the parameter to plot on the x-axis 
* y: [<parameter>] the parameter to plot on the y-axis 
* z: [<parameter>] in case of a 3d plot, the parameter to plot on the z-axis

The supported parameters are:

* time: simulation elapsed time
* x (y,z): position components of the state vector
* altitude: altitude above ground
* semi_major: semi-major axis of the orbit in meters
* eccentricity: orbital eccentricity
* inclination: orbital inclination with respect to Earth equator in degrees
* ascending_node: longitude of the ascending node in degrees
* argument_of_periapsis: argument of the periapsis in degrees
* true_anomaly: the true anomaly of the orbit in degrees
* latitude: current latitude over which the spacecraft is
* longitude: current longitude over which the spacecraft is
* radius: current radius with respect to the center of gravity
* vx (vy, vz): velocity components of the state vector
* vtot: length of the velocity vector
* x1 (y1, z1): position components of the state vector relative to the first defined celestial body
* vx1 (vy1, vz1): velocity components of the state vector relative to the first defined celestial body
* body_x (body_y, body_z): position of the first defined celestial body
* r1: distance to the first defined celestial body
* target_prox_x (target_prox_y, target_prox_z): distance relative to orbital target in prograde (normal, radial) direction 
* target_prox_vx (target_prox_vy, target_prox_vz): velocity relative to orbital target in prograde (normal, radial) direction 

4.0 Comments

The software doesn't do miracles and fits typically only work for sane requests which don't have unreasonable Delta-v requirements. It is easily possible to set up PEG-4 targets which can't be fulfilled, so start fits with care. 

All ignition time fits treat the specified time in the burn definition as the lower bracket of the search window - if the optimal time is yet power, the fit won't converge but stay on the bracket.

Generally fitting solutions requires some background knowledge of what you're doing. 

A series of tutorials can be found at 

http://www.science-and-fiction.org/science/leo_targeting.html

Feedback and Patches are welcome!

Thorsten Renk 2017-2019
thorsten@science-and-fiction.org
