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.

You can use pre-defined meta flags and use the minus sign to remove specific flags from the standard. Meta-flags should be processed before individual flags set or unset.

A list of flags can be found 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.

epsnumber

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

cutoffnumber | 1D array of numbers

distance limit for orbits used as termination condition (cm)

for 1D array, provide distance limits for each Jacobi coordinate

for scalar, assume same distance limit for all Jacobi coordinates

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.

Configuration

In a special section toml the behaviour of toml file interpretation can be adjusted. Currently, the following entries are supported

unusedtrue | false

whether to print list of unused variables (default: true)

underscorestrue | false

whether to use (true) an underscore in a variable name as separator for unit and to indicate that a string value is to be evaluated.

Default is to use underscores for separation for briefness of expressions.

Note

If this is used, variable names must not contain underscores

eval

list of regular expressions to trigger string evaluation. Default is to evaluate of the string starts with an @ symbol or the expression is encased in curly braces (standards from Kepler code).

The strings are interpreted as Python regular expressions. It uses re.fullmatch() on the stripped string (str.strip()) to extract the content.

Note

You need to include the (single) open/close brackets to capture the string you want to evaluate.

Default:

eval = [r'@(.*)', r'{(.*)}']

Example

[toml]
unused = true
underscores = false
eval = ['[\^_!@$](.*)', '<(.*)>', '{(.*)}']

Evaluation of variables

Beyond the specifications of toml files, variable names and values are processed if the variable name

contains an underscore if enabled in the configuration.
contains (potentially void) unit in brackets

Note

In toml files, variable and section names are allowed to contain non-word characters, however, they then need to be in quotation marks.

In the variable name, the section after the underscore (if enabled) or that in brackets 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 (if enabled) or a bracket and the value after the underscore or in the bracket is a string, it is evaluated as Python numerical expression, using the constants as defined in the dictionary in config.py and in the scales section. A subset of NumPy functions, as well as some special functions form multistar have been imported for use in evaluation as well. The quantity after the underscore, if present, is interpreted as the unit of the quantity. This can (apparently) even be a literal number - you have to produce a legal toml name, however, but you _may_ use quotation marks to accomplish that.

R_RSUN = 1
M_1e-12 = 2
"P_2*YR" = 7
"an(AU)" = 2
"wn()" = "2*PI/YR"

All physical values are in cgs units by default.

Scales

In the optional scales section, global constants can be defined. 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. This will affect, obviously, scales with circular references. Issue may also arise when overwriting default scales.

These scales can be used as units in other sections as well as in the general section. The scales section is evaluated first.

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 object, star, planet, or asteroid 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 or single-element array 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.

Shadows

The optional shadow section allows to define shadow runs for stability analysis. If the section is not present, no shadows are generated.

Note

If shadows are present, both original and shadows can be accessed as independent multistar runs using the index operator; the original has index 0. Data (y and y0) is not copied (no extra memory), but uses NumpPy slice. All other properties are shallow copies.

Note

If a termination condition occurs in the original or any shadow, such as collision, the execution is terminated immediately w/o continuing later shadows, and status_shadow is set to the image number that caused the exception, with index 0 being the reference run.

Note

Shadows are not used for derivatives.

The following entries are allowed:

nint: number of shadows, excluding original image, default: 1

Setting perturbation

epsfloat | array of floats: magnitude of random variation of quantities in units of scale vector yscale. If an array, it must have same shape as y0 of the original image as last dimension. Array of shape (n, len(y0)).
epsrfloat | array of floats: magnitude of random variation of position in units of scale vector yscale. If an array, it must have same shape as position component of y0 (3 * norb).
epsvfloat | array of floats: magnitude of random variation of velocity in units of scale vector yscale. If an array, it must have same shape as velocity component of y0 (3 * norb).
epsjfloat | array of floats: magnitude of random variation of angular momentum in units of scale vector yscale. If an array, it must have same shape as spin component of y0 (3 * nstar).
epsofloat | array of floats: magnitude of random variation of orientation vector in units of scale vector yscale (usually \(\pi\)). If an array, it must have same shape as orientation component of y0 (3 * nstar).

Note

This requires orientation uses orientation vectors, which is not default. This can have very unexpected results.
epsffloat | array of floats: magnitude of random variation of orientation quaternion in units of scale vector yscale (usually \(1\)). If an array, it must have same shape as orientation component of yscale (4 * nstar).

Note

This requires orientation uses orientation quaternions, which is default. This should be well-behaved.
d(multi-D) array of floats: set absolute value of perturbation. Array of shape (n, len(y0)).
dr(multi-D) array of floats: set absolute value of position perturbation. Array of shape (n, norb, 3).
dv(multi-D) array of floats: set absolute value of velocity perturbation. Array of shape (n, norb, 3).
dj(multi-D) array of floats: set absolute value of angular momentum perturbation. Array of shape (n, nstar, 3).
do(multi-D) array of floats: set absolute value of orientation vector perturbation. Array of shape (n, nstar, 3).

Note

This requires orientation uses orientation vectors, which is not default. This can have very unexpected results.
df(multi-D) array of floats: set absolute value of orientation quaternion perturbation. Array of shape (n, nstar, 4).

Note

This requires orientation uses orientation quaternions, which is default. This should be well-behaved.
del(multi-D) array of floats: set relative value of perturbation in units of the scale vector yscale. Array of shape (n, len(y0)).
delr(multi-D) array of floats: set relative value of position perturbation in units of the scale vector yscale. Array of shape (n, norb, 3).
delv(multi-D) array of floats: set relative value of velocity perturbation in units of the scale vector yscale. Array of shape (n, norb, 3).
delj(multi-D) array of floats: set relative value of angular momentum perturbation in units of the scale vector yscale. Array of shape (n, nstar, 3).
delo(multi-D) array of floats: set relative value of orientation vector perturbation in units of the scale vector yscale. Array of shape (n, nstar, 3).

Note

This requires orientation uses orientation vectors, which is not default. This can have very unexpected results.
delf(multi-D) array of floats: set relative value of orientation quaternion perturbation in units of the scale vector yscale. Array of shape (n, nstar, 4).

Note

This requires orientation uses orientation quaternions, which is default. This should be well-behaved.
y(multi-D) array of floats: set value of shadow orbit. Array of shape (n, len(y0)).
r(multi-D) array of floats: set value of position. Array of shape (n, norb, 3).
v(multi-D) array of floats: set value of velocity. Array of shape (n, norb, 3).
j(multi-D) array of floats: set value of angular momentum. Array of shape (n, nstar, 3).
o(multi-D) array of floats: set value of orientation vector. Array of shape (n, nstar, 3).

Note

This requires orientation uses orientation vectors, which is not default. This can have very unexpected results.
f(multi-D) array of floats: set value of orientation quaternion. Array of shape (n, nstar, 4).

Note

This requires orientation uses orientation quaternions, which is default. This should be well-behaved.

Additionally, a one-based number may be appended to refer to specific orbit or object, the middle dimension of the vector is then dropped accordingly.

Some special cases have been implemented for each variation scheme (eps, d’, del, and ‘’):

rv: combination of r and v in one array of shape (n, 2 * norb, 3)
rxy: radius slice in xy plane, array of shape (n, norb, 2)
vxy: velocity slice in xy plane, array of shape (n, norb, 2)
rvxy: combination of radius and velocity slice in xy plane, array of shape (n, 2 * norb, 2)

# triple star system setup in xy-plane

[scales]
del = 1e-13

[shadow]
n = 8
delrvxy_del = 'eye(8,8).reshape(-1,4,2)'

The provided arrays need to be broadcastable to the desired shape; in particular, for \(n=1\) the first dimension may be dropped.

# Random variation of first orbit in the xy plane

[shadow]
epsr1 = [1e-12, 1e-12, 0]

Note

Obviously, all conflicts are invalid exclusions. Unspecified values are assume zero.

If multiple shadows are needed where specific values can be set for each more conveniently, shadow can be an array.

# test two shadows with orthogonal perturbations

[[shadow]]
delr1 = [1e-12, 0, 0]

[[shadow]]
delr1 = [0, 1e-12, 0]

Setting truncation for termination

This optional section diverge allows to specify the truncation cutoff. There is only one common divergence criterion for all shadows. Default is no truncation.

Note

If truncation occurs, status is set to STATUS_DIVERGE, status_shadow is set to the corresponding image number and status_component is set to the solution vector component number.

epsfloat | array of floats: magnitude of variation of quantities in units of scale vector yscale. If an array, it must have same shape as y0 of the original image. Array of shape (len(y0),).
epsrfloat | array of floats: magnitude of variation of position in units of scale vector yscale. Array of shape (norb, 3).
epsvfloat | array of floats: magnitude of variation of velocity in units of scale vector yscale. Array of shape (norb, 3).
epsjfloat | array of floats: magnitude of variation of angular momentum in units of scale vector yscale. Array of shape (nstar, 3).
epsofloat | array of floats: magnitude of variation of orientation vector in units of scale vector yscale (usually \(\pi\)). Array of shape (nstar, 3).

Note

This requires orientation uses orientation vectors, which is not default. This can have very unexpected results.
epsffloat | array of floats: magnitude of variation of orientation quaternion in units of scale vector yscale (usually \(1\)). Array of shape (nstar, 4).

Note

This requires orientation uses orientation quaternions, which is default. This should be well-behaved.
d(multi-D) array of floats: set absolute value of perturbation. Array of shape (len(y0),).
dr(multi-D) array of floats: set absolute value of position perturbation. Array of shape (norb, 3).
dv(multi-D) array of floats: set absolute value of velocity perturbation. Array of shape (norb, 3).
dj(multi-D) array of floats: set absolute value of angular momentum perturbation. Array of shape (nstar, 3).
do(multi-D) array of floats: set absolute value of orientation vector perturbation. Array of shape (nstar, 3).

Note

This requires orientation uses orientation vectors, which is not default. This can have very unexpected results.
df(multi-D) array of floats: set absolute value of orientation quaternion perturbation. Array of shape (nstar, 4).

Note

This requires orientation uses orientation quaternions, which is default. This should be well-behaved.

In the same way as for the perturbation setup, broadcasting can be used. Orbit and star numbers can be used, except for the plain d and eps.

Note

Set values you do not want to limit to inf.

[diverge]
eps = 1e-6

[diverge]
epsr = [1e-5, 1e-5, inf]
epsv = [1e-5, 1e-5, inf]

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

(only partially implemented)

TQQ

Tidal quadrupole-quadrupole interaction.

This is a higher-order correction to pure monopole-qudrupole interaction in literature.

(not yet implemented)

T3Q

hierarchical triple tide in paired quadruple approximation

(not implemented)

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
ORIENTATION: turn on tracking of angular momentum and orientation

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 file is 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 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.

Replacing and adjusting of entry units

When using the set method, the key is replaced by the new key name, unless the keyword convert is set to True (convert to original units).

toml.set('orbit.an', 3.e14)
toml.set('orbit.an_au', 2., convert=True)

In the above example, they entry orbot.an will be in cgs units, and the numerical value will be that of two au in cm.

Note

When array indices are used, conversion is enforced.

toml.set('orbit.euler(deg)', = [0, 0, 90])
toml.set('orbit.euler(rad)[2]', np.pi/2)

This will retain the orbit.euler(deg) key.

In the item assignment form, conversion is also enforced, preserving the original key and its name with unit.

toml['orbit.an(au)'] = 3.

This will retain the orbit.au key (in cgs units) and set the value to that of three au in cm.

Array indices

For values that are arrays, the NumPy/array square bracket syntax can be used to set specific array values. In this case, however, only numerical values are allows, no strings for later evaluation.

If combined with units, the unit is part of the key name, the index square bracket comes later.

When using indices, the original key unit is preserved. The assignment, however, can use a different unit; unit transforms are still done correctly, just the key name including unit remain unchanged.q

Note

The ability to use array index on assignment is is why square bracket was not used for unit syntax.

toml.set('orbit.euler_deg[1]', 90)
toml['orbit.euler(deg)[0]'] = 45

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.
value – value to use.

We can’t set a string template if index is provided.
convert – What to do about the key used.

True
convert to 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

Functions explicitly defined for use in expression evaluation

sqrt

cbrt

exp

log

log10

sin

cos

tan

cot

1 / numpy.tan

arcsin

numpy.arcsin

arccos

numpy.arccos

arctan

numpy.arctan

arccot

numpy.arctan (1 / x)

arctan2

sinh

cosh

tanh

coth

1 / numpy.tanh

arcsinh

numpy.arcsinh

arccosh

numpy.arccosh

arctanh

numpy.arctanh

arccoth

numpy.arctanh (1 / x)

e

numpy.exp (1)

GOLDEN

(1 + numpy.sqrt (5)) / 2

golden ratio

sinx

multistar.distributions.sinx()

cosx

multistar.distributions.cosx()

asinx

multistar.distributions.asinx()

acosx

multistar.distributions.acosx()

random_sample

numpy.random.random_sample()

random_integers

numpy.random.random_integers()

eye

numpy.eye()

diag

numpy.diag()

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