Config#

The general system configuration is defined in a toml file. In the general (root) section basic setting and global defaults are set. Details for orbits, objects, and gravitational waves, plotting, etc., are set in separate sections.

General section#

version

file version (current: 10100)

fullbool

whether to use full N-body interaction

If not provided, will be selected by type

excludes hierarchical

hierarchicalbool

whether to use hierarchical N-body interaction

If not provided, will be selected by type

excludes full

secularbool

use secular code (currently only available for binaries)

excludes direct

directbool

use direct code (default)

excludes secular

type

type of system, string or int

'single', '1', 1

single object setup

'direct', 'secular', 'double', 'binary', '1+1', '2', 2

binary setup

If 'secular' is selected, the secular binary code is use, overwriting secular or direct flags

If 'direct' is selected, the direct binary code is use, overwriting secular or direct flags

Unless specified otherwise, use direct code by default.

'triple', 'ternary', '2+1', '3', 3

triple star setup

If full or hierarchical is not specified,

'triple', '3', and 3 result in full code,
'ternary' and '2+1' results in hierarchical code

'quadruple', 'quaternary', 'qh', '2+1+1', '4', 4

quadruple star setup in hierarchical Jacobi coordinates

If full or hierarchical is not specified,

'quadruple', '4', and 4 result in full code,
'quaternary' and '2+1+1' results in hierarchical code

'2+2', '2x2', 'qp'

quadruple star setup in pair-of-pairs Jacobi coordinates

If full or hierarchical is not specified, use hierarchical code by default.

'gw'

quadruple code for gravitational wave studies, pair-of-pairs setup.

'poly', 'multi', 'polyadic', 'multiple', 'pf', 'n'

full dynamical multi-star code, not yet implemented

flags

physics flags, usually given as space-separated string for flags (see below)

namestring

name of model, used in plots

commentstring

provide some info about this run, printed on setup

Note

Comments at the TOML file level are ignored in parsing and are lost when the configuration data is written to file. In contrast, the content of the comment entry is retained.

refstring

some references, printed on model setup

angles'absolote' | 'relative'

default setting whether angles are absolute or relative

data'setup' | 'model'

whether to use object values from toml file or from data file

pathstring

global path for data files

timenumber

time offset used for star data and GW data (default: 0)

objectslist of strings

name of sections for objects

If not specified, some defaults (to be spelled out here) is used

orbitslist of strings

name of sections for orbit specifications

If not specified, some defaults (to be spelled out here) is used

dtminnumber

minimum time step of model (s)

default is usually 1

tbeginnumber

start time of run (s)

default is 0

This is relative to time offset time

tendnumber

end time for run (default: 100,000 s) if not specified in run command

tmaxnumber

maximum wall clock time (s) for run

nstepnumber

default value for number of steps used by

dtnumber

default value for time to run (s) for rund() or default time step for runs()

dt0number

default initial (internal) time step (s) for integrator

set by module otherwise, usually 1 for dynamical cases

dtdnumber

default value for minimum time between outputs for rund() (s)

yscalerfnumber

Scale factor for reference distance used in integrator for accuracy limit.

orientationbool

directive to use body orientations.

It sets the flag ORI.

Maybe better to just set the ORI flag directly.

quaternionbool

directive to use quaternions for body orientations.

It sets the flag ORQ.

Maybe better to just set the ORQ flag directly.

epsnumber

accuracy for integrator (default is \(10^{-13}\)).

cutoffnumber | array of numbers

distance limit for orbits used as termination condition (cm)

interactscalar | 1D array of numbers | 2D array of numbers

interaction distance for pairs of objects

for 2D arrays, provide square matrix of size number of objects

for 1D array, provide vector of length (number of objects - 1) \(\times\) (number of objects - 2). For three objects, these correspond to the combinations (1,2), (1,3), and (2,3).

for scalar, all matrix entries are set to the same value

t0number

set default zero time for model data and gw data (s); default: 0

Qnumber

default tidal dissipation quality

taunumber

default tidal lag time (s)

timenumber

base time for run (s), default is 0

alignbool | str

set default alignment of deformed bodies.

See Orientation of non-spherical bodies.

Evaluation of variables#

Beyond the specifications of toml files, variable names and values are processed if the variable name contains an underscore. Note that in toml files, variable and section names are allowed to contain white spaces but then need to be in quotation marks.

In the variable name, the section after the underscore is interpreted as a unit, which can be either from the dictionary in config.py, or specified in the scales section.

If the variable name contains an underscore and the value is a string, it will be evaluated as Python numerical expression, using the constants as defined in the dictionary in config.py and in the scales section.

All physical values are in cgs units by default.

Scales#

In the optional scales section, global constants can be defined. The entries in the section are evaluated in order as provided, the code does not sort by dependencies (and then has to deal with circular references). These scales can be used as units in other sections as well as in the general section. The scales section is evaluated first.

In the current version, a simple brute-force algorithm has been implemented trying to resolve scales recursively out-of-order. Scales that cannot be resolved become undefined. Issue may also arise when overwriting default scales. See Config API for details.

Orbits#

The names of orbit sections are specified using the orbits key of the General section.

If orbits is not provided, an array of name orbit or binary can be used for automatic (internal) numbering. If there is only one orbit, orbit or binary may be just a section (table) rather than an array (default names).

Object coordinate setup#

Orbits can be derived from object coordinates and velocities or explicit orbit descriptions. This is done using the setup key

setup'coord' | 'orbit'

'coord': use coordinate mode
'orbit': use orbit mode

Default is to use orbit mode unless any of the objects has coordinates or velocities defined. Currently, one cannot mix orbit and coordinate modes within one setup although come combinations may be logically possible.

Direct Jacobi coordinate setup#

Orbits can be specified using explicit values for Jacobi coordinates

rlist of three numbers: radius vector (cm)
vlist of three numbers: velocity vector (cm/s)

Instead, one can also specify individual components. This can be more convenient when overwriting values on setup.

rxnumber: x-component of radius vector (cm)
rynumber: y-component of radius vector (cm)
rznumber: z-component of radius vector (cm)
vxnumber: x-component of velocity vector (cm/s)
vynumber: y-component of velocity vector (cm/s)
vznumber: z-component of velocity vector (cm/s)

The phase on the orbit, assuming Keplerian orbital elements, can be set using

tnumber: time relative to specified coordinates (s)

Note

If direct coordinate setup is used and no explicit orbit properties are needed, no orbit section may be needed. In case no orbits are provided, an array with name orbit and empty entries is generated.

Orbital elements setup#

More convenient can be to specify orbital elements. By default, orbits are oriented along the positive x-axis and perpendicular to the z-axis, with angular momentum in direction of the positive z-axis.

A variety of quantities have been defined, the intent is to allow viable, sufficient, and non-conflicting parameters, however, not all possible combinations may have been implemented and not all possible conflicts identified. Please advise if you encounter any issues; in particular, solutions are most welcome.

e

Runge-Lenz vector

en

numerical eccentricity

an

magnitude of semi-major axis (cm)

rp

periapsis distance (cm)

ra

apoapsis distance (cm)

Only useful for eccentric orbits.

ln

norm of semi-latus rectum (cm)

P

period (s)

wn

angular velocity (rad/s)

b

impact parameter

for hyperbolic orbits only

vinf

velocity at infinity (cm/s)

for hyperbolic orbits only

ascending

longitude of ascending node (rad)

inclination

inclination (rad)

periapsis

argument of periapsis (rad)

eulerarray of three numbers

Euler angles (rad)

(ascending, inclination, periapsis)

H

orbital angular momentum (erg s)

h

specific orbital angular momentum (erg s / g)

H / reduced mass

Hn

norm of orbital angular momentum (erg s)

hn

norm of specific orbital angular momentum (erg s / g)

EE

total orbital energy (erg)

Ee

specific orbital energy (erg/g)

EE / total mass

Position on orbit#

tau

time on orbit relative to periapsis (s)

negative values are before periapsis

rn

distance at current location (cm)

negative values are before periapsis

phase

fraction of phase normalised to 1

mean anomaly / 2 pi

mean

mean anomaly (rad)

eccentric

eccentric anomaly (rad)

anomaly

true anomaly (rad)

GR orbits#

grbool: use 1PN corrections to set up circular orbits

TODO - add other PN setup routines

Some aliases#

true: anomaly
true anomaly: anomaly
mean anomaly: mean
argument of periapsis: periapsis
eccentric anomaly: eccentric
longitude of ascending node: ascending

Note

In toml files, keys with spaces can be used in quotation marks.

'argument of periapsis_deg' = 90

General orbit parameters#

namestr

name of orbit, used in plots

[orbit]
name = 'planet orbit'

colorrgb spec

color of orbit, used in plots

color = 'red'
color = '#f30000'

commentstr

additional user information stored with orbit

Note

Comments at the TOML file level are ignored in parsing and are lost when the configuration data is written to file. In contrast, the content of the comment entry is retained.

Objects#

Object sections#

The names of objects sections are specified using the objects key of the General section.

objects = [star, planet, moon]

These will be the keys for the object sections.

Key names that are not valid Python names can be specified using quotation marks

objects = ['Star A', 'Star B', 'Planet c']

If objects is not provided, an array of name star or object can be used for automatic numbering (but you can’t mix).

[[star]]
M_Msun = 4

[[star]]
M_Msun = 2

[[star]]
M_Mjup = 1

If all objects have the same property, a single section named star or object can be used to describe them all.

Note

The code still implicitly creates an array, in case you need to access — get or set — properties using the Config API. You can access the mass, e.g., using

m.toml['star[1].M']

Object properties#

Object properties can be set statically in the TOML file or time-dependent values be read from file. The data value in each object section may be

datastr

"model": select model setup
"setup": select object configuration from TOML file

The default value for data can be set in the General section.

data = 'model'

If data is not defined, if an object section has the key model (see below), it defaults to "model" and to "data" otherwise (see below). Strictly speaking, it is not needed, maybe of historic origin, but better to specify explicitly for clarity).

Setup from model data#

The data is generated from the str file from a Kepler run. The time offset for the model (usually, starting time at \(t=0\)) is set using the t0 (s) entry.

modelstr: name of model data file
t0number: zero time for model (s)
timenumber: specific time relative to t0 used during model setup (s).

['Star A']
model = '~/kepler/runs/s15/s15.data'
t0_kyr = 30

A default value for t0 can also be set on the General section.

If t0 is not set, it defaults to 0.

The time entry allows to overwrite to the time used to determine object values of M, I, and S used during setup. time is measured relative to each model’s t0 value. The model’s time entry is not used otherwise during the simulation.

TODO: Description of model data format and how to generate

Setup from TOML file#

General object parameters#

namestr

name of object, used in plots

[star]
name = 'planet orbit'

colorrgb spec

color of object, used in plots

color = 'red'
color = '#f30000'

commentstr

additional user information stored with object

Note

Comments at the TOML file level are ignored in parsing and are lost when the configuration data is written to file. In contrast, the content of the comment entry is retained.

Object mass#

M: mass of object (g)

Object dimensions#

R

radius of object (cm)

S

radius (size) of object (cm)

S is used for historical reasons (Mardling & Lin (2002))

TODO - remove

diameter

twice radius

For deformed bodies, the shape can be specified in terms of ellipsoids with specific axes sizes

axes: body axes sizes
dims: twice body axes sizes

These are only used as a convenient way to compute the moment of inertia tensor, assuming a body of constant density. If this is not a good description of the object, set the moment of inertia tensor explicitly.

An alternate way to describe deformed bodies is to use oblateness and asphericity (or alpha):

oblateness: object oblateness
asphericity: object asphericity
alpha: asphericity \(\times\,\sqrt{1/3}\)

Note

Relations and limits for oblateness and asphericity

The moment of inertia tensor diagonal components are proportional to

\(A = y^2 + z^2\)

\(B = x^2 + z^2\)

\(C = x^2 + y^2\)

where \(x\), \(y\), and \(z\) are the body axis lengths. We then have the relation

\(A \le B \le C \leftrightarrow z < y < x\)

With this, asphericity, \(a\), and oblateness, \(o\) are defined as

\(a = \sqrt{(B-A)/C}\)

\(o = 1 - \sqrt{(A+B-C)/C}\)

Given \(a\) and \(o\), the specific moment normalised of inertia tensor components can be computed as

\(C = 3\,I / [2 + (1 - o)^2]\)

\(B = C\,[(1-o)^2/4 + a^2/2] + 3/4\,I\)

\(A = 3\,I - B - C\)

where \(I\) is the gyration factor, in the literature typically referred to as \(k^2\) or just \(k\). For a sphere, and default here, this is \(2/5\) by default, but can be overwritten using the I entry.

The total moment of inertia tensor is computed from mass or density of the object.

Oblate solutions have \(B < C\), which requires

\(o \le 1 - \sqrt{1 - a^2}\)

(limit for prolate solution around Axis A)

Prolate solutions have \(A > C\), which requires

\(o \le 1 - \sqrt{1 + a^2}\)

(limit for oblate solution around Axis B)

Negative asphericity just flips the axes, whereas positive asphericity keeps the axes monotonous.

multistar, however, sorts moment of inertia tensor component sin ascending order, so for asphericity, effectively, only the magnitude is considered.

Object density#

Density can be used to connect body mass and radius, or to compute body mass from dimensions.

rho: body average density (\(\mathrm{g}\,\,mathrm{cm}^{-3}\))

Moment of inertia#

Inumber | list of three numbers

number: scalar moment of inertia for spherical bodies
list of numbers: moment of inertia tensor in diagonal form

(in cgs units, \(mathrm{g}\,\mathrm{cm}^2\))

if \(I \le 1\), assume it is the dimensionless specific gyration radius

inumber | list of three numbers

specific gyration radius

relative to I, or, if I is not provided, relative to that of a sphere of constant density

Note

For any body, the moment of inertia will be sorted in ascending order such that the “shortest axis” is aligned with the z axis. Rotation about the short axis is, for a given angular momentum, the stable (lowest energy) solution.

Tidal properties#

k: apsidal motion constant
tau: tidal lag time (s)
Q: quality of orbital motion

Note

Only one of tau and Q can be provided.

Warning

For systems other than binary orbits, the use of Q does not make really senses, and hence it should be seen as a historical artefact.

Values for black holes#

a

black hole spin parameter of vector (g)

use to compute an and set BH spin

an

scalar black hole spin parameter (g)

used to compute spin-corrected radius of event horizon or set magnitude of BH spin

If \(a < 1\) assume it is the dimension-less spin-parameter \(\chi\) and scale by M.

chi

dimension-less scalar spin parameter

used to set an

Note

Use of a, an, or chi indicates that we set up a BH.

Rs

radius in Schwarzschild radii

Ss

radius in Schwarzschild radii

(historical name, remove)

Rg

radius in graviational radii (half Schwarschild radius)

Note

If neither Rg nor Rs are provided, compute radius from general spin-dependent formula for \(r_+\):

\(R = G\,c^{-2}\,\left(M + \sqrt{M^2 - a^2}\right)\)

Sg

radius in graviational radii (half Schwarschild radius)

(historical name, remove)

Is

moment of inertia in units of Schwarzschild BH values (\(4\,G^2\,M^3\,c^{-4}\))

Ig

moment of inertia in gravitational units (\(G^2\,M^3\,c^{-4}\))

Note

If neither Ig nor Is are provided, compute radius from general spin-dependent formula for \(r_+\):

\(I = 2\, G^2\,c^{-4}\,M^2\,\left(M + \sqrt{M^2 - a^2}\right)\)

This should actually be a tensor (vector of diagonal elements for tensor in normal form) to get correct mass quadrupole moment.

\(Q_{zz} = -\frac13\, G^2\,M\,a^2\,c^{-4}\)

\(Q_{xx} = Q_{yy} = -\frac12\, Q_{zz}\)

and we should use

\(I_{zz} = 2\, G^2\,c^{-4}\,M^2\,\left(M + \sqrt{M^2 - a^2}\right)\)

\(I_{xx} = I_{yy} = I_{zz} - G^2\,M\,a^2\,c^{-4}\)

where we use our definition for \(Q = \frac13 \mathrm{Tr}(I) - I\).

Currently, however, there is no code to update the BH moment of inertia tensor or use the BH quadrupole moment. I could be set statically, however, and would require to enable quadrupole interactions.

Warning

No default values for k, tau, or Q are set. The default is that they are zero, e.g., there is no induced tides and no tidal dampening. Whereas this is probably wrong, the effect may be small.

Please let me know if you have a suggestion what the correct values should be.

TODO: BH quadrupole moment

Setting initial orientation of an object and of its angular momentum#

For rotating bodies, (e.g., tidally deformable) spherical objects, the initial spin orientation needs to be set.

Spin from model data#

The spin can be taken from a Kepler dump if the object section has a dump entry

[star]
dump = '~/kepler/runs/s15/s15#zams'

If the dump uses 3D angular momentum, is spin orientation is taken, otherwise the spin is oriented in z-direction by default.

Spin from configuration#

May different ways, usually you can specify the vector of a quantity, or magnitude and direction. If no direction is specified, orientation along positive z axis is assumed.

If angular velocity is provided for deformed bodies, the corresponding angular momentum vector is computed such that the (initial) angular velocity is as set. They are, in general, not aligned, except if aligned with one of the body axes.

J

angular momentum vector (erg s)

j

specific angular momentum (erg s / g)

\(J = j \times M\)

w

angular velocity vector (rad/s)

a

BH spin vector (g)

an

BH spin parameter (g)

Jn

magnitude of angular momentum (erg s)

wn

angular velocity (rad/s)

P

period (s)

vrot

equatorial rotation velocity (cm/s)

erot

rotation energy (erg)

jn

magnitude of specific angular momentum

Je

direction of angular momentum

je

same as Je

we

direction of angular velocity

ae

direction of BH spin

3D rotation of spin vector#

By default, the spin vector is aligned with the z-axis, but it may also have a different direction if set explicitly or loaded from a stellar model. Additionally, a 3D rotation can be applied to the spin vector:

euler: 3D rotation of spin axis provided as Euler rotations

Note

The last angle is rotation about the spin axis and does not affect spin, however, it may impact the orientation of a deformed body of orientation is relative the spin vector (default).
rot: 3D rotation of spin axis provided as rotation vector
quat: 3D rotation of spin axis provided as unit quaternion

Spin orientation from observational data#

The star rotation can also be rotated based on observational data (relative to z-axis) based on orbit, inclination, and projected obliquity (lambda)

referencestr

name of reference orbit

The reference orbit need to have Euler angles defined.

inclination

spin inclination

lambda

spin projected obliquity

See Liang+2022.

rotation: additional rotation about spin axis

Orientation of non-spherical bodies#

For non-spherical objects, additionally, the orientation needs to be specified. The orientation is usually assumed relative to the orientation of the 3D rotation used to set the spin orientation.

This is set as using the orientation entry.

The default orientation of a body is with the short axis in z-direction and the second-longest axis in y-direction.

orientationnumber | list of three numbers | list of four numbers

single number: rotation (rad) about the z-axis (short axis of object)
list of three numbers: rotation vector (rad)
list of four numbers: rotation quaternion (rad)

orienteulerlist of three numbers

Euler rotation vector (rad)

By default, the orientation of the body is aligned with spin, i.e., the orientation spatial rotations is applied after the spatial rotation for the spin. This can be changed using the align entry

alignstr | bool

'spin', 'Yes', 'yes', 'YES', True: align orientation is relative to spin (default)
'independent', None, 'no', 'No', 'NO', False: align orientation is independent of spin (default)

Note

It is essential to understand that transformation used to set the spin orientation has three degrees for freedom (e.g., when using three Euler angles), however, whereas the rotation about the spin axis does not affect the spin axis, it does affect the orientation of non-spherical bodies if alignment (align) is set to align with spin.

Standard flags#

NG: Newtonian gravity
SD: spin distortion
TD: tidal distortion
TF: tidal Friction
PN: first order post-Newtonian (1PN)
SO: second order post-Newtonian spin-orbit coupling
P2: second order post-Newtonian point-pass corrections (2PN)
SS: second order post-Newtonian spin-spin interaction
RR: relativistic radiation (2.5PN), gauge as in Kidder (1995)
PNF: use post-Newtonian correction factor on torques for angular momentum conservation
SDH: use hierarchical spin distortion (direct3h, …)
TDH: use hierarchical tidal distortion (direct3h, …)
TFH: use hierarchical tidal friction (direct3h, …)
PNH: use hierarchical post-Newtonian corrections (direct3h, …)
PNQ: use binary-binary post-Newtonian (direct4p)
TFN: use mean motion for calculation of tidal friction (Mardling & Lin 2002)
TD3: use three-body tidal interaction
SDT: no idea
TDT: no idea
TFT: no idea
PNT: no idea
T3T: no idea
T3H: no idea
T3R: no idea
T3S: no idea
QP: Use pair of binaries as Jacobi configuration of quadruple stars
ORI: track orientation of deformed bodies
ORQ: use quaternions to track orientation
ORS: track orientation of non-deformed spinning bodies
PQM: use permanent quadrupole moment (this includes QP-MP interactions?)
PQH: no idea, likely quadrupoles in hierarchical systems
PQQ: use permanent quadruple moment QP-QP interactions
CD: use collision detection for deformed bodies
SQQ: QP-QP interactions for spin-distorted stars (may not be implemented)
TQQ: no idea
GW: enable gravitational wave features
RRB: switch to use RR formulation (gauge) of Blanchet (2024), requires RR
P3: third-order post-Newtonian corrections (3PN, Blanchet 2024), requires RRB (and, hence, implicitly also requires RR)
P35: post-Newtonian corrections of order 3.5 (3.5PN, Blanchet 2024), requires P3 (and, hence, implicitly also requires RR and RRB)
EIH: Einstein-Infeld-Hoffmann (EIH) equations for first order post-Newtonian corrections

Flag	Requirement	Exclusions
RRB	RR
P3	RR RRB
P35	RR RRB P3
EIH	NG	P2 P3 P35 RR RRB

Compound flags#

DYN: plain point-mass dynamics
DYNAMICS: same as DYN
DEFAULT: dynamics, 1PN, tidal interaction (similar to Mardling & Lin 2002, but for multiple bodies)
PNDYN: plain point-mass 1PN dynamics (e.g., Kidder 1995)
GR2DYN: plain 2PN point-mass dynamics (e.g., Kidder 1995, Blanchet 2024)
GR25DYN: plain 2.5PN point-mass dynamics (Blanchet 2024, ‘harmonic gauge’)
GR3DYN: plain 3PN point-mass dynamics (Blanchet 2024)
GR35DYN: plain 3.5PN point-mass dynamics (Blanchet 2024)
GRDYN: plain 2.5PN point-mass dynamics (Kidder 1995)
GRSPIN: 2.5PN dynamics with spin, no tides (Kidder 1995)
NONE: no interaction
QUDRUPOLE: permanent quadruple and tidal interaction, no PN
GREIH: plain dynamics with EIH first order post-Newtonian corrections

gw#

Direct time-dependent gravitational wave specification.

Can be an array of sections.

Note

Use [[gw]] for each section.

Keys are

namestring

name of GW source component

mode'strain' | 'amplitude' | 'binary'

mode of GW setup

t

time of GW signal (s)

t0

reference time of GW signal (s)

tmin

start time of GW signal (s)

tmax

end time of GW signal (s)

alpha

inclination of BH binary relative o GW direction

anomaly

initial phase angle of GW (rad)

M1

mass of BH 1 (g)

M2

mass of BH 1 (g)

M

chirp mass (g)

assume equal-mass binary

excludes use of M1 and M2

P

period of GW signal (s)

2 pi / angular frequency

f

frequency of GW signal (Hz)

angular frequency / 2 pi

w

initial angular frequency of GW (rad/s)

n

mode (default 2)

A

amplitude (default 1)

used in mode binary

Ap

‘plus’ polarisation amplitude

use in mode amplitude

Ax

‘cross’ polarisation amplitude

use in mode amplitude

d

distance to source (cm)

used in mode binary

(ddot{h} amplitude scales as W**(8/3)/d

xi

factor on omega-dot

…

phase: anomaly / 2 pi
anomaly: TBD
euler: Euler angles of source (rad)

gwave#

Section for GWAVE settings used by module gravity

List of flags#

USE: switch on use of gwave functions for direct binary-binary GW interactions
ECC: use eccentric orbit(s) for back-extrapolation of retarded locations and QP time derivatives
RET: use retarded times. LIN and ECC select those extrapolations, circular otherwise.
LIN: use linear backward extrapolation of location given current velocity for retarded locations
REL: relativistic redshift (not implemented)
RAB: relativistic aberration (not implemented)
FRZ: freeze binary centre of mass locations. all other forces are active
ISO: isolate binaries. Only GW interaction
NEF: near field gravitational QP interaction. By default, direct QP-QP interaction is disabled. Use NQQ to enable QP-QP terms.
PN1: first order post-Newtonian interaction
BQP: binary quadruple-monopole interaction only. Use full nearfield NQQ.
BMP: binary monopole-monopole interaction only. Use full nearfield NQQ.
REC: use recorded location for retarded signals and QP values and derivatives (not implemented)
RND: Retarded Newtonian Dynamics (not implemented)
NQQ: non-dot quadrupole term in nearfield approximation. Requires one of (ISO, BMP, BQP).
PN2: second order post-Newtonian interaction, requires PN1 (not implemented)
P25: 2.5 order post-Newtonian interaction, requires PN1, PN2 (not implemented)

Config API#

This API can be used to modify the TOML file before generating a multstar object. This is useful for parameter studies where a ‘template’ TOML file is modified. It should be loaded using

from multistar.config import Config
toml = Config('/path/to/my_toml_file')

The configuration file is stored in the toml attribute. It can be accessed using dotted key syntax for dictionaries.

toml['orbit.an_km']

For keys names that only contain characters that are allowed as valid Python variable names, as a conveniences, it is possible to access directly:

toml.orbit.an_mm

Existing values can be overwritten by assignment to the value

toml['Star A.radius_cm'] = 3.e8

Warning

The non-dictionary style is not allowed for assignments! It fails without any indication, warning, or error message.

Keys can be removed using the usual Python del intrinsic or by assigning None.

Non-existing keys can be added using the multistar.config.Config.set() method explicitly:

toml.set('Star A.diameter_km', 5.e8)

Sections, called tables in TOML documentation, can be added using multistar.config.Config.addtable()

toml.addtable('star 1')

Arrays of sections, called arrays in TOML documentation, can be added using multistar.config.Config.addarray(), new array entries can be added using multistar.config.Config.addarrayitem() and array entries can be deleted using multistar.config.Config.delarrayitem().

toml.addarray('stars', n=3)

Starting with multistar.config.Config.new(), a complete configuration can be generated from scratch using this API, so no template would be needed.

Units are always allowed, both for input and output.

Note

Entries to the scales special section lead to updated evaluation of the values, in order as defined in the TOML file.

The optional pos argument to the set method allows to me move an entry to a new location (zero-based) for this purpose. In all other cases, dictionary access should be position-independent.

toml.set('scales.length', 1.e8, pos=0)
toml.set('scales.volume_', 'length**3')

The current revision, however, interactively evaluate scales until all resolvable scales are resolved; unresolvable scales are not set, but will be set as soon as they become resolvable. Unresolvable scales are stored in toml._unresolved_scales.

Special code has been added to allow consistent overwriting of default scales/unis; this, however, seems rather unwise. Overwritten units/scales are stored in toml._overwritten_scales.

If the overwritten unit/scale is invalid/unresolved, it cannot be used and may result in subsequent errors. The original unit is not used in lieu, as this may result in silent corruption of values.

Methods#

Config.__init__(toml, kinds=None, silent=False, kwargs=None)#

Configuration interface.

Parameters:

toml (str | dict | None) – name of file to load, dictionary of values, or None for empty configuration
kinds (dict) – dictionaly of kinds to return for values
silent (bool) – suppress output (default: False)
kwargs (dict) – alternative values, stored in self.kwargs.

Used by multistar.config.Config.value() for some “tricks” that now seem obsolete.

classmethod Config.new(*args, filename=None, **kwargs)#

create new empty Config

Parameters:

filename – set filename (used for saving, default: None)
Other arguments are passed to ``Config``.

Config.addtable(name)#

add new section (table)

Parameters:: name (str) – name of section

Config.addarray(name, n=1)#

add new array, including first empty table (TOML default)

Parameters:

name (str) – name of array
n (int) – number of entries to add, minimum and default is 1

Config.addarrayitem(name, n=1, pos=-1)#

add new array entry/entries

Parameters:

name (str) – name of section
n (int) – number of entries to add (default: 1)
pos (int) – position where to add

Config.delarrayitem(name, index)#

add new array entry/entries

Parameters:

name (str) – name of section
index (int | slice) – entries to remove

Note

slice instance has to be created explicitly, array syntax does not work on function calls in Python.

Config.set(key, value, convert=False, pos=None)#

Parameters:

key – fully qualified key name

array (of tables) indices use zero-based square bracket notation

subtables and entries are separated by dots

If key contains an index into an array-shaped entry, conversion is enforced, an ‘evaluation string’ is not allowed in this case.
convert –

True
convert ot existing unit

Ellipis
replace by base

False
replace entry (default)
pos – new postion (0-based) of entry in table

negative values are counted from the back, as usual

positions outside of the range are truncated to the range, no warning on range violations is given.

m.toml.set('time', 0.)
m.toml.set('gw[3].time[2]', 3)

Config.setarr(key, index, value)#

replace value at index in array

Parameters:

key – name of key
index – may be any valid NumPy array index compatible with existing array
value – compatible NumPy array

Config.update(entries: dict) → None#

update several entries, similar to dict’s update method

Parameters:: entries (dict) – dictionary of entries to update

Example

from multistar.config import Config as C
from multistar import multi as M
c = C('-eight')
d = {
    'star[1].m_Msun': 2,
    'star[2].m_Msun': 3,
     }
c.update(d)
m = M(c)

Note

Update does not implicitly create new sections. New sections have to be added first, by assigning an empty dictionary (”{}”) to a key. Similarly, new arrays are not created implictly, you need to first assigning a list with at least one (empty) dictionary (”[{}]”) to a key. Using this method, no new array entries can be added to existing arrays.

Config.updated(entries: dict) → Config#

return updated config

Parameters:: entries (dict) – dictionary of entries to update
Returns:: Copy of config with updated values

Example

from multistar.config import Config as C
from multistar import multi as M
c = C('-eight')
d = {
    'star[1].m_Msun': 2,
    'star[2].m_Msun': 3,
     }
m = M(c.updated(d))

Note

Update does not implicitly create new sections. New sections have to be added first, by assigning an empty dictionary (”{}”) to a key. Similarly, new arrays are not created implictly, you need to first assigning a list with at least one (empty) dictionary (”[{}]”) to a key. Using this method, no new array entries can be added to existing arrays.

Config.delete(key: str) → None#

delete key

Parameters:: key (str) – name of key

Config.get(key, default=<class 'object'>)#

return value or sub-table

Parameters:

key – fully qualified key name

array indices use zero-based square bracket notation

subtables and entries are separated by dots

Config.value(key, default=<object object>, *, parameter=None, kw=None, pop=True, kind=None)#

return evaluated value

Parameters:

key – fully qualified key name

array indices use zero-based square bracket notation

subtables and entries are separated by dots
parameter – retuen this value if not None
kw – return value of this keyword from self.kwargs if defined and not None
pop – remove entry from self.kwargs
kind – specify return vakue type

Config.write(filename=Ellipsis, overwrite=False, return_contents=False)#

config file writer

filename: str | None | Ellipsis

str: name of file
None: print to terminal
Ellipsis: save to load file name (default)

overwrite: bool

True: if filename exists, overwrite it
False: raise AttributeError if file exists (default)

return_contentsbool

return file contents as string

Returns:: Contents of TOML file as string if return_contents is True.

Config.print(screen=True)#

print config to terminal

Parameters:: screen (bool) – print generated TOML file contents to screen if True (default)
Returns:: generated TOML file contents if screen is False

Config.copy()#

make deep copy

Returns:: deep copy of config

Config.compare(other)#

compare with other configuration

Parameters:: other (Config) – configuration to compare

Prints results to screen.

Config.get_config_entry(key)#

obtain raw config entry

Parameters:: key (str) – name of key
Returns:: raw config key including units, as currently stored

Config.get_config_value(key)#

obtain raw config value

Returns:

raw config value, which may be string that would be
evaluated when using get or value methods

Config.haskey(name)#

Test whether name exists

Parameters:

name (str) – name of section, array, or entry

Returns:

True – if name exists
False – otherwise

Config.isscalar(name)#

Test whether name exists and is a “scalar”

Parameters:

name (str) – name of section, array, or entry

Returns:

True – if name exists and is not an TOML array and not a TOML table
False – otherwise

Config.istable(name)#

Test whether name exists and is an TOML table

Parameters:

name (str) – name of section, array, or entry

Returns:

True – if name exists and is an array
False – otherwise

Config.isarray(name)#

Test whether name exists and is an TOML array

Parameters:

name (str) – name of section, array, or entry

Returns:

True – if name exists and is an array
False – otherwise

Config.keys()#: standard dictionary interface dict.keys().

Config.values()#: standard dictionary interface dict.values()

Config.items()#: standard dictionary interface dict.items()

Config.subkeys(trim: bool = True) → list[str]#

return list of all sub-keys

Parameters:: trim – exclude unit base in name
Returns:: list of full keys that can be used in Config.update().

Note

In contrast to dict.keys() this is not a life view.

Config.subitems(trim: bool = True) → list[str, Any]#

return list of all (sub-key, value) pairs

Parameters:

trim – exclude unit base in name

Returns:

list of full (keys, value) pairs that can be used in
Config.update().

Note

In contrast to dict.items() this is not a life view.

Config.subvalues(trim: bool = True) → list[Any]#

return list of all values

Parameters:: trim – exclude unit base in name
Returns:: list of all sub-key values.

Note

In contrast to dict.values() this is not a life view.

Config.subitemsdict(trim: bool = True) → dict#

return dict of all {sub-key: value} pairs

Parameters:: trim – exclude unit base in name
Returns:: dictionary of all {sub-key (value} pairs.)

Note

This is not a life view.

Config.sectionkeys() → list[str]#

return list of all section keys

Returns:: list of all section keys that can be used in Config.set().

Note

In contrast to dict.keys() this is not a life view.

Config.sectionitems() → list[str, Config]#

return list of all (section keys, section) pairs

Returns:: list of all (section key, section) that can be used in Config.set().

Note

In contrast to dict.items() this is not a life view.

The sections themselves, however, are live views.

Config.sectionvalues() → list[Config]#

return list of all sections

Returns:: list of all sections that can be used in Config.set().

Note

In contrast to dict.values() this is not a life view of entries.

The sections themselves, however, are live views.

Config.sections() → {}#

return dictionary of all sections

Returns:

dictionary of all sections by qualified name that can be used
in Config.set().

Note

In contrast to dict.items() this is not a life view of entries.

The sections themselves, however, are live views.

Config.__or__(other: Config) → Config#

chain two configurations

Parameters:: other (Config) – configuration to use for update
Returns:: New object with combined configuration

Note

Requires same base
cannot create new or delete section arrays or section array entires in first array

Default scales (units)#

s

cm

g

Hz

kHz

1e3

mHz

1e-3

uHz

1e-6

nHz

1e-9

Gyr

1e9 * YR

Myr

1e6 * YR

kyr

1e3 * YR

tH

13.7e9 * YR

Hubble time

YR, yr, year

YR

d, day

DAY

ds

DAY * YR / (YR + DAY)

sidereal day

h

hour

min, minute

au, AU

AU

kau, kAU

1e3 * AU

Mau, MAU

1e6 * AU

Gau, GAU

1e9 * AU

mau, mAU

1e-3 * AU

uau, uAU

1e-6 * AU

mau, nAU

1e-9 * AU

deg, degree

deg2rad

arcmin

deg2rad / 60

arcsec

deg2rad / 3600

mas

deg2rad / 3600000

uas

deg2rad / 3600000000

nas

deg2rad / 3600000000000

rad

1

radian

1

Lsun, LSUN

LSUN

amu, AMU

AMU

Msun, MSUN

MSUN

Mearth, MEARTH, Me

5.972e27

Rearth, REAETH, Re

6.3781e8

Mj, Mjup, Mjupiter

1.89813e30

Rj, Rjup, Rjupiter

7.1492e9

Mmoon

7.34767309e25

nMsun

1.e-9 * MSUN

uMsun

1.e-6 * MSUN

mMsun

1.e-3 * MSUN

kMsun

1.e3 * MSUN

MMsun

1.e6 * MSUN

GMsun

1.e9 * MSUN

TMsun

1.e12 * MSUN

PMsun

1.e15 * MSUN

EMsun

1.e18 * MSUN

Rsun, RSUN

RSUN

mp

np.sqrt(HBAR*CLIGHT/GRAV)

“Planck mass”

lp

np.sqrt(HBAR*GRAV/CLIGHT**3)

“Planck length”

tp

np.sqrt(HBAR*GRAV/CLIGHT**5)

“Planck time”

Tp

np.sqrt(HBAR*CLIGHT**5/GRAV*KB**2)

“Planck temperature”

ng

1e-9

ug

1e-6

mg

1e-3

kg

1e3

t

1e6

kt

1e9

Mt

1e12

Gt

1e15

Tt

1e18

m

100

km

1e5

Mm

1e8

Gm

1e11

Tm

1e14

Pm

1e17

Em

1e20

mm

0.1

um

1e-4

nm

1e-7

pm

1e-10

fm

1e-13

ly

CLIGHT * YR

LY

CLIGHT * YR

pc

PC

PC

PC

mpc

1e-3 * PC

kpc

1e3 * PC

Mpc

1e6 * PC

Gpc

1e9 * PC

PI, Pi, pi

np.pi

G, GRAV

GRAV

c, CLIGHT

CLIGHT

kms

1e5

kmh

1e5 / 3600

rads

1

radmin

1 / 60

radh

1 / 3600

radd

1 / 86400

radyr

1 / YR

revs

2 * np.pi

revmin

2 * np.pi / 60

revh

2 * np.pi / 3600

revd

2 * np.pi / 86400

revyr

2 * np.pi / YR

erg

1

J

1.e7

kJ

1.e10

MJ

1.e13

GJ

1.e16

TJ

1.e19

PJ

1.e22

EJ

1.e25

ZJ

1.e28

YJ

1.e31

“yotta” Joule

RJ

1.e34

“ronna” Joule

QJ

1.e37

“quetta” Joule

B

1e51

“Bethe”

meV

1.602176634e-15

eV

1.602176634e-12

keV

1.602176634e-9

MeV

1.602176634e-6

GeV

1.602176634e-3

TeV

1.602176634

Config#

General section#

Evaluation of variables#

Scales#

Orbits#

Object coordinate setup#

Direct Jacobi coordinate setup#

Orbital elements setup#

Position on orbit#

GR orbits#

Some aliases#

General orbit parameters#

Objects#

Object sections#

Object properties#

Setup from model data#

Setup from TOML file#

General object parameters#

Object mass#

Object dimensions#

Object density#

Moment of inertia#

Tidal properties#

Values for black holes#

Setting initial orientation of an object and of its angular momentum#

Spin from model data#

Spin from configuration#

3D rotation of spin vector#

Spin orientation from observational data#

Orientation of non-spherical bodies#

Standard flags#

Compound flags#

gw#

gwave#

List of flags#

Config API#

Methods#

Default scales (units)#

This Page