Input File Format¶

Input files are plain text files in the form:

category.parameter = setting

Lines in the input file that can not be parsed in this manner are ignored. Comments can be entered with either a “,” or a “#”. Everything in a line after a comment character is ignored. There are currently seven categories that can be set: geometry, surface_interaction, forces, spatial_dist, speed_dist, angular_dist, and options. The required parameters for each category are not fixed; i.e., which paramters are needed depends somewhat on the settings chosen. Below, all possible parameters for each category are defined. Input files are case insensitive.

Geometry¶

The geometry can be defined either with a timestamp (i.e., determine the geometry values at a defined epoch), or without a timestamp (i.e., by specifying important values). If running the model from MESSENGERdata.model(), the geometry is determined from from the data and geometry settings in the input file are ignored.

Geometry With Time Stamp¶

geometry.planet [Required]: Central planet for the model. This must be an object that orbits the Sun.
geometry.StartPoint [Optional]: Object from which packets are ejected. This must be an object in the planetary system (the planet or one of its moons). Default = geometry.planet.
geometry.objects [Optional]: Objects to include in calculations given as comma-separated list of bodies in the planetary system. For example, if geometry.objects = Jupiter, Io, the gravity effects of the other moons would not be included, nor would collisions with their surfaces. Default is to include all defined objects for the system.
geometry.startttime [Required]: Starting time for the model run in ISOT format (YYYY-MM-DDTHH:MM:SS). The true anomaly angle, subsolar point, and orbital position of moons are determined using SPICE.

Geometry Without Time Stamp¶

geometry.planet [Required]: Central planet for the model. This must be an object that orbits the Sun.
geometry.StartPoint [Optional]: Object from which packets are ejected. This must be an object in the planetary system (the planet or one of its moons). Default = geometry.planet.
geometry.objects [Optional]: Objects to include in calculations given as comma-separated list of bodies in the planetary system. For example, if geometry.objects = Jupiter, Io, the gravity effects of the other moons would not be included, nor would collisions with their surfaces. Default is to include all defined objects for the system.
geometry.phi [Required if planet has moons.]: Orbital phase of each included moon relative to the Sun in radians given as a comma-separated list. Measured from 0 rad to 2π rad where 0 rad is superior conjunction and π/2 rad is over the planet’s dawn terminator. The number of values must be equal to the number of non-planet objects included.
geometry.subsolarpoint [Optional]: The sub-solar longitude and latitude over the planet’s surface in radians given as comma-separated values. For Jupiter, use System-III central meridian longitude. Sub-solar latitude isn’t used for anything currently, but could in the future be used to include effects of the planetary system’s tilt relative to the Sun.
geometry.TAA [Required]: Planet’s True Anomaly Angle in radians. This is used to determine the planet’s distance and radial velocity relative to the Sun.

SurfaceInteraction¶

The SurfaceInteraction class defines interactions between packets and body surfaces. The available parameters depend on the interactions desired. If no values are provided, 100% sticking is assumed.

Constant Sticking Coefficient¶

surfaceinteraction.stickcoef [Optional]: Sticking coefficient to be used uniformly across the body’s surface. For complete surface sticking, set surfaceinteraction.stickcoef = 1.. For no sticking (100% of packets are reemitted from the surface, set surfaceinteraction.stickcoef = 0. Default = 1.
surfaceinteraction.accomfactor [Required if stickcoef < 1]: Surface accommodation factor. 1 = Fully accommodated to local surface temperature. 0 = Elastic reemission.

Temperature Dependent Sticking Coefficient¶

The sticking coefficient follows the functional form (Yakshinskiy & Madey 2005):

\[S(T) = A_0 e^{A_1 T} + A_2\]

where the coefficients are species dependent. For Na, \(A_0=1.57014, A_1=-0.006262, A_2=0.1614157\).

surfaceinteraction.sticktype [Required]: Set surfaceinteraction.sticktype = temperature dependent.
surfaceinteractions.accomfactor [Required]: Surface accommodation factor. 1 = Fully accommodated to local surface temperature. 0 = Elastic reemission.
surfaceinteractions.A [Optional]: Comma separated values for the coeffeicients. Default = 1.57014, 0.006262, 0.1614157. (Ideally the defaults will be species dependent, but I only have values for Na.)

Sticking Coefficient from a Surface Map¶

surfaceinteraction.type [Required]: Set surfaceinteraction.sticktype = from map.
surfaceinteraction.sticking_mapfile [Required]: Path to the file containing a map of the sticking coeficient. The format for the map has not been determined.
surfaceinteractions.accomfactor [Required]: Surface accommodation factor. 1 = Fully accommodated to local surface temperature. 0 = Elastic reemission.

Forces¶

The Forces class determines which forces are included in the simulation. Currently, the model only includes gravity and radiation pressure. If no forces are set in the input file both are included by default.

forces.gravity [Optional]: True to include gravity; False to exclude. Default = True.
forces.radpres [Optional]: True to include radiation pressure; False to exclude. Default = True

SpatialDist¶

The SpatialDist class specifies the initial spatial distribution of packets in the system. Currently, three spatial distribution types are defined, all of which place packets over the surface (or exobase) of geometry.StartingPoint. More distributions may defined upon request.

Coordinate Systems

The coordinate system used for the object’s latitude and longitude depends on whether the packets are ejected from a planet or a moon. For planets, a solar-fixed coordinate system is used where the longitude increases in the positive direction from the sub-solar point (noon) point to dusk point:

sub-solar (noon) point = 0 rad = 0°
dusk point = π/2 rad = 90°
anti-solar (midnight) point = π rad = 180°
dawn point = 3π/2 rad = 270°

For satellites, the coordinate system is planet-fixed from the sub-planet point increasing positive through the leading point:

sub-planet point = 0 rad = 0°
leading point = π/2 rad = 90°
anti-planet point = π rad = 180°
trailing point = 3π/2 rad = 270°

Latitude ranges from -π/2 rad to π/2 rad for the south pole to the north pole. All angular values are given in radians in the input file.

Uniform Surface¶

Distribute packets randomly across a region of the surface or exobase with a uniform probability distribution.

spatialdist.type [Required]: Set spatialdist.type = uniform.
spatialdist.longitude [Optional]: Longitude range on the surface to place packets in radians given as long0, long1 where \(0 \leq long0,long1 \leq 2\pi\). If long0 > long1, the region wraps around. Default = 0, 2π.
spatialdist.latitude [Optional]: Latitude range on the surface to place packets in radians given as lat0, lat1 where \(-\pi/2 \leq lat0 \leq lat1 \leq \pi/2\).
spatialdist.exobase [Optional]: Location of the exobase in units of the starting point’s radius. Default = 1.

To eject all packets from a single point, set long0 = long1 and lat0 = lat1; i.e., to eject all packets from the sub-solar point of a planet, set:

spatialdist.longitude = 3.14159,3.14159
spatialdist.latitude = 0,0

Spatial Distribution from a Surface Map¶

Distribute packets according to a probability distribution given by a pre-defined surface map.

spatialdist.type [Required]

Set spatialdist.type = surface map.

spatialdist.mapfile [Optional]

Set this to a pickle or IDL savefile containing the map information, or set to ‘default’ to use the default surface composition map.

The sourcemap is saved as a dictionary with the fields:

longitude: longitude axis in radians

latitude: latitude axis in radians

abundance: surface abundance map

coordinate_system: planet-fixed, solar-fixed, or moon-fixed

If not given, the default, planet-fixed surface composition map is used.

spatialdist.subsolarlon [Optional]

Sub-solar longitude for the observation in radians. This is required for a planet-fixed coordinate system. However, if simulating a MESSENGER orbit, this value will be overwritten by the value at the time the data were taken. If it is required, but not given or specified programmatically, an Exception will be raised.

spatialdist.exobase [Optional]

Location of the exobase in units of the starting point’s radius. Default = 1.

Surface-Spot Spatial Distribution¶

Distribute packets with a spatial distribution that drops off exponentially from a central point.

spatialdist.type [Required]: Set spatialdist.type = surface spot.
spatialdist.longitude [Required]: Longitude of the source center in radians.
spatialdist.latitude [Required]: Latitude of the soruce center in radians.
spatialdist.sigma [Required]: Angular e-folding width of the source in radians.
spatialdist.exobase [Optional]: Location of the exobase in units of the starting point’s radius. Default = 1.

SpeedDist¶

The SpeedDist class defines the one-dimensional initial speed distribution of the packets. Currently implemented speed distributions are gaussian, Maxwellian, sputtering, and flat. More can be added upon request.

Gaussian (Normal) distribution¶

Packets speeds are chosen from a normal distribution. See numpy.random.normal for more information on the implementation.

speeddist.type [Required]: Set speeddist.type = gaussian
speeddist.vprob [Required]: Mean speed of the distribution in km/s.
speeddist.sigma [Required]: Standard deviation of the distribution in km/s.

Maxwellian Distribution¶

Packet speeds are chosen from a Maxwellian distribution given by:

\begin{eqnarray*} f(v) & \propto & v^3 \exp(-v^2/v_{th}^2) \\ v_{th}^2 & = & 2Tk_B/m \end{eqnarray*}

speeddist.type [Required]: Set speeddist.type = maxwellian
speeddist.temperature [Required]: Temperature of the distribution in K. Set speeddist.temperature = 0 to use a pre-defined surface temperature map (Not implemented yet).

Sputtering Distribution¶

Packet speeds are chosen from a sputtering distribution in the form:

\begin{eqnarray*} f(v) & \propto & \frac{v^{2\beta + 1}}{(v^2 + v_b^2)^\alpha} \\ v_b & = & \left(\frac{2U}{m} \right)^{1/2} \end{eqnarray*}

speeddist.type [Required]: Set speeddist.type = sputtering
speeddist.alpha [Required]: \(\alpha\) parameter.
speeddist.beta [Required]: \(\beta\) parameter.
speeddist.U [Required]: Surface binding energy in eV.

Flat Distribution¶

Packet speeds are uniformly distributed between vprob - delv/2 and vrpob + delv/2. Setting speeddist.delv = 0 gives a monoenergetic distribution.

speeddist.type [Required]: Set speeddist.type = flat
speeddist.vprob [Required]: Mean speed of the distribution in km/s.
speeddist.delv [Required]: Full width of the distribution in km/s.

AngularDist¶

The AngularDist class defines the initial angular distribution of packets. The options are radial and isotropic. More distributions can be added upon request. If not given, an isotropic distribution into the outward facing hemisphere is assumed.

Radial Distribution¶

Packets are ejected radially from the surface.

angulardist.type [Required]: Set angulardist.type = radial.

Isotropic Distribution¶

Packets are ejected isotropically into the outward facing hemisphere (if the packets are starting from the surface) or the full hemisphere. angulardist.type is not given, an isotropic distribution is assumed and all other options are ignored (i.e., altitude and azimuth can not be specified).

angulardist.type [Optional]: Set angulardist.type = isotropic.
angulardist.altitude [Optional]: Used to limit the altitude range of the distribution. Given as a comma-separated list of altmin, altmax in radians measured from the surface tangent to the surface normal.
angulardist.azimuth [Optional]: Used to limit the azimuth range of the distribution. Given as a comma-separated list of az0, az1 in radians. This should be measured with azimuth = 0 rad pointing to north, but I’m not sure if it actually works. Use of this option is not recommended.

Options¶

The Options class sets runtime options that don’t fit into other categories.

options.endtime [Required]: The total simulated runtime for the model. Generally chosen to be several times the lifetime of the species.
options.species [Required]: The species to be simulated.
options.lifetime [Optional]: The lifetime due to ionization or dissociation of the species in seconds. If options.lifetime = 0, the lifetime is computed based on available ionization and dissociation reactions. If options.lifetime > 0, the lifetime is constant throughout the system. If options.lifetime < 0, the lifetime is assumed to be the photo-lifetime and no loss occurs in the geometric shadow. Default = 0 (use available reactions).
options.outer_edge [Optional]: Distance from geometry.startpoint to simulate in object radii. Default = infinite; i.e., no outer edge is given to the simulation.
options.step_size [Optional]: Time step size for the simulation in seconds. Set options.step_size = 0 for variable step size. Default = 0 (variable step size). If step_size is non-zero, the number of steps to be run is endtime/step_size + 1.
options.resolution [Optional]: Relative precision of the simulation. Default = \(10^{-4}\). This is ignored if options.step_size is set.