Skip to content

Principia configuration files

Jump to bottom Edit New page
Robin Leroy edited this page Jan 9, 2022 · 20 revisions

Principia configuration files

Definitions of scalar types

string is any text that can be stored in a value of a KSP configuration node and retrieved by GetValue.

fixed_step_size_integrator is the name of a fixed step size integrator supported by Principia. [Note that this is case-sensitive.]

See also the comments on the declarations of the symplectic partitioned Runge-Kutta integrators, symplectic Runge-Kutta-Nyström integrators, and symmetric linear multistep integrators and the references cited therein for more on these integrators.

fixed_step_size_integrator ⩴ BLANES_MOAN_2002_SRKN_6B
                           | BLANES_MOAN_2002_SRKN_11B
                           | BLANES_MOAN_2002_SRKN_14A
                           | MCLACHLAN_1995_SB3A_4
                           | MCLACHLAN_1995_SB3A_5
                           | MCLACHLAN_ATELA_1992_ORDER_4_OPTIMAL
                           | MCLACHLAN_ATELA_1992_ORDER_5_OPTIMAL
                           | OKUNBOR_SKEEL_1994_ORDER_6_METHOD_13
                           | QUINLAN_1999_ORDER_8A
                           | QUINLAN_1999_ORDER_8B
                           | QUINLAN_TREMAINE_1990_ORDER_8
                           | QUINLAN_TREMAINE_1990_ORDER_10
                           | QUINLAN_TREMAINE_1990_ORDER_12
                           | QUINLAN_TREMAINE_1990_ORDER_14

floating_point_number is a floating point number as accepted by std::strtod.

signed_integer is a signed integer as accepted by std::strtol in base 10.

unit is one of the following units, as defined in quantities/parser_body.hpp:

length_unit      ⩴ μm | mm | cm | m | km | au
time_unit        ⩴ ms | s | min | h | d
power_unit       ⩴ W
angle_unit       ⩴ deg | ° | rad
solid_angle_unit ⩴ sr

unit             ⩴ length_unit | time_unit | power_unit | angle_unit | solid_angle_unit

quantity is defined by the following grammar from quantities/parser.hpp:

quantity            ⩴ floating_point_number quotient_unit
quotient_unit       ⩴ quotient_unit / exponentiation_unit
                    | / exponentiation_unit
                    | product_unit
product_unit        ⩴ exponentiation_unit [product_unit]
exponentiation_unit ⩴ unit [^ exponent]
exponent            ⩴ signed_integer

We will use quantity(length), quantity(length / time^2), etc. to refer to quantities that are required to have the dimensions given in parentheses.

Example: -1.5e+09 km/s is a quantity(length / time).

instant is a date either given as a Julian Date or a Modified Julian Date (where the decimal mark must be a full stop "."), or as an ISO 8601 complete representation of date and time, where Principia requires that the comma "," be used as a decimal sign if a decimal fraction of seconds is used. It is interpreted as TT (Temps Terrestre, terrestrial time).

Example: JD2451545.0, MJD51544.5, 2000-01-01T12:00:00, 1999-W52-6T12:00:00,000, 2000001T120000 all represent the standard epoch J2000.

colour is an HTML style colour code in RGB order.

Example: #aaff32

style is one of the following styles, as defined in ksp_plugin_adapter/gl_lines.cs:

style            ⩴ solid | dashed | faded

The top-level configurations

Principia supports four top-level configuration nodes. There may be at most one of each node [for instance, having two principia_gravity_model nodes will result in a crash]. These are principia_gravity_model which defines the physical properties of the celestial bodies, principia_initial_state which defines their initial positions and velocities, principia_numerics_blueprint which defines the numerical methods used to compute the evolution of the system, and principia_draw_styles which defines drawing styles for trajectories.

If principia_initial_state is provided, it must define the initial positions and velocities for all celestial bodies, and principia_gravity_model must be sufficient for all celestial bodies.

If principia_initial_state is not provided, the initial state is obtained by interpreting KSP's orbital elements as osculating elements for Jacobi coordinates. In that case, principia_gravity_model need not cover all celestial bodies. It must be nominal for the bodies it covers.

The principia_gravity_model configuration

The principia_gravity_model configuration consists of a sequence of body configuration nodes.

A body configuration node contains the following values:

A body configuration node is nominal if:

  • j2 and geopotential_rows are not present at the same time;
  • either reference_radius is absent, or one of j2 and geopotential_row is present;
  • no two geopotential_rows share the same degree;
  • within each geopotential_row, no two geopotential_columns share the same order;
  • each geopotential_column contains exactly one of cos and j;
  • each geopotential_column whose degree is not 0 contains a cos.

A sufficient body configuration node is a nominal body configuration node where:

  • gravitational_parameter, reference_instant, axis_right_ascension, axis_declination, reference_angle, and angular_frequency are present;
  • reference_radius is present if and only if j2 or geopotential_rows are present.

Example: All body nodes in sol_gravity_model.cfg, provided with Principia, are sufficient. The Sun has a j2. The giant planets have geopotential_rows that use j. The Earth, the Moon, Mars, and some other planets have geopotential_rows that use cos.

Semantics of the quantities used for body rotation

The quantities W = W0 + Ẇ (t - t0), α0, and δ0 are Euler angles defining the orientation of the celestial body, as shown on figure 1 of the 2009 report of the IAU Working Group on Cartographic Coordinates and Rotational Elements, where t is terrestrial time.

Semantics of the quantities used for extended-body gravitation

The gravitational potential used is the one given in equation 6.1 of IERS technical note 36 (IERS conventions 2010), where:

μ = GM and J2 = -C̄20 √5.

Note: A dynamically oblate body has a positive J2. The values for the planets of the solar system can be found, with references, in sol_gravity_model.proto.txt.

The principia_initial_state configuration

The principia_initial_state configuration consists of:

  • a game_epoch value;
  • a solar_system_epoch value;
  • a sequence of body configuration nodes.

The game_epoch is a required instant, which is the instant at which the game starts. The solar_system_epoch is a required instant, which is the instant at which the initial state is given.

It is required that solar_system_epoch≤game_epoch.

The body nodes must contain the following values:

  • name: a required string. This is the name of the celestial body whose initial state is being defined.
  • x: a required quantity(length). The x coordinate of the position.
  • y: a required quantity(length). The y coordinate of the position.
  • z: a required quantity(length). The z coordinate of the position.
  • vx: a required quantity(length / time). The x coordinate of the velocity.
  • vy: a required quantity(length / time). The y coordinate of the velocity.
  • vz: a required quantity(length / time). The z coordinate of the velocity.

Example: The sol_initial_state_jd_2433282_500000000.cfg configuration file, provided with Principia, is a valid principia_initial_state node.

The principia_numerics_blueprint configuration

The principia_numerics_blueprint configuration consists of:

  • an optional ephemeris node;
  • an optional history node;
  • an optional psychohistory node.

The ephemeris node contains the following values:

  • fixed_step_size_integrator, a required fixed_step_size_integrator;
  • integration_step_size, a required quantity(time).
  • fitting_tolerance, a required quantity(length).
  • geopotential_tolerance, a required floating_point_number.

The integration of the motion of the celestial bodies is performed by the ephemeris with the given fixed_step_size_integrator at the given integration_step_size. The result of the integration is approximated by a polynomial with a maximum error given by fitting_tolerance. Any geopotential effects are ignored if their relative magnitude with respect to the central force is less than geopotential_tolerance.

Example: The following principia_numerics_blueprint node describes the default numerics blueprint used by Principia.

principia_numerics_blueprint {
 ephemeris {
   fixed_step_size_integrator = QUINLAN_TREMAINE_1990_ORDER_12
   integration_step_size      = 10 min
   fitting_tolerance = 1 mm
   geopotential_tolerance = 0x1.0p-24
 }
}

☡ The history and psychohistory nodes are reserved for internal use. Modders should not define these nodes.

The history node contains the following values:

  • fixed_step_size_integrator, a required fixed_step_size_integrator;
  • integration_step_size, a required quantity(time).

The psychohistory node contains the following values:

  • adaptive_step_size_integrator, a required adaptive_step_size_integrator;
  • length_integration_tolerance, a required quantity(length);
  • speed_integration_tolerance, a required quantity(length / time).

The principia_draw_styles configuration

The principia_draw_styles configuration consists of:

  • an optional history node;
  • an optional prediction node;
  • an optional flight_plan node;
  • an optional burn node;
  • an optional target_history node;
  • an optional target_prediction node.

Each of these nodes contain the same set of values:

  • colour, a required colour;
  • style, a required style.

Example: The following principia_draw_styles node describes the default draw styles used by Principia.

principia_draw_styles {
 history {
   colour = #aaff32    // Lime
   style = faded
 }
 prediction {
   colour = #ed0dd9    // Fuchsia
   style = solid
 }
 flight_plan {
   colour = #8f99fb    // Periwinkle Blue
   style = dashed
 }
 burn {
   colour = #ff81c0    // Pink
   style = solid
 }
 target_history {
   colour = #fac205    // Goldenrod
   style = faded
 }
 target_prediction {
   colour = #c292a1    // LightMauve
   style = solid
 }
}

The principia_override_version_check configuration

Principia performs a strict check of the KSP version in use. This means that, for instance, a version of Principia built for KSP 1.11.2 refuses to start in a KSP 1.11.3 or 1.12.0 installation. We realize that users might want to try newer versions of KSP that are not yet supported by Principia, or that KSP installations might be automatically updated by Steam. Therefore, we provide an escape hatch that makes it possible to override the version check. Note however that there will be no support whatsoever if the version check is overridden.

The principia_override_version_check configuration consists of a list of version values indicating for which versions of KSP the check should be overridden.

Example: The following principia_override_version_check node overrides the version check when using Principia with KSP versions 0.24.2, 1.11.3 and 2.0.666 (if that ever exists). Obviously, while 1.11.3 is a reasonable version to try to use, there is not a chance in hell of Principia working with KSP 0.24 or with KSP 2.

principia_override_version_check {
  version = 0.24.2
  version = 1.11.3
  version = 2.0.666
}

Annex: choosing a fixed step size integrator

The symmetric linear multistep integrators tend to be faster when they have converged to small errors, but they can fail catastrophically if they are not yet converged.

The single-step methods (symplectic partitioned Runge-Kutta, symplectic Runge-Kutta-Nyström) produce physically credible behaviour even when they have errors resulting from an overly large time step.

Solar system designers should test the actual stability of their system with a symplectic Runge-Kutta-Nyström method and a small time step, and then try increasing the step size and switching to a linear multistep integrator to reduce computational cost for their users.

Annex: a note on ModuleManager

The constraint that there may be at most one of each top-level configuration applies after ModuleManager has run.

In the absence of other mods, none of the configurations are present. With RealSolarSystem, the principia_gravity_model and principia_initial_state nodes are both present, since they use a :NEEDS[RealSolarSystem] clause.

Modders should make careful use the @ operator (modify an existing node) and :NEEDS[] clause (condition on the presence of a mod) to ensure the requirement is met.

Example: a modder creating a mod AdditionalRealBodies which adds bodies to RealSolarSystem should append their initial states to principia_initial_state and their sufficient gravity models to principia_gravity_model with @principia_initial_state:FOR[AdditionalRealBodies]:NEEDS[RealSolarSystem] and @principia_gravity_model:FOR[AdditionalRealBodies]:NEEDS[RealSolarSystem].

A modder creating a new solar system mod NeuesSonnensystem should create nominal gravity models in a node without any ModuleManager predicates, principia_gravity_model. Alternatively, they can create sufficient gravity models in that node and provide an initial state inprincipia_initial_state.

If the author of NeuesSonnensystem wishes some aspect of the system to be conditioned on the presence or absence of Principia, they can do so in a patch @Kopernicus:FOR[NeuesSonnensystem]:NEEDS[Principia] or @Kopernicus:FOR[NeuesSonnensystem]:NEEDS[!Principia].

Note that the mathematical operators of ModuleManager will not work on the quantity values of Principia configuration nodes. Since ModuleManager is Turing-complete, we leave it as an exercise to the reader to perform arithmetic on these values.

Modders should refer to the ModuleManager thread for documentation.

Principia for Kerbal Space Program. For support, join the IRC, or go to the KSP-RO discord server and go to the respective channel.

Versions

Clone this wiki locally