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: General section --------------- version file version (current: :code:`10100`) full : bool whether to use full N-body interaction If not provided, will be selected by type excludes :code:`hierarchical` hierarchical : bool whether to use hierarchical N-body interaction If not provided, will be selected by type excludes :code:`full` secular : bool use secular code (currently only available for binaries) excludes :code:`direct` direct : bool use direct code (default) excludes :code:`secular` type type of system, string or int :code:`'single'`, :code:`'1'`, :code:`1` single object setup :code:`'direct'`, :code:`'secular'`, :code:`'double'`, :code:`'binary'`, :code:`'1+1'`, :code:`'2'`, :code:`2` binary setup If :code:`'secular'` is selected, the secular binary code is use, overwriting :code:`secular` or :code:`direct` flags If :code:`'direct'` is selected, the direct binary code is use, overwriting :code:`secular` or :code:`direct` flags Unless specified otherwise, use *direct* code by default. :code:`'triple'`, :code:`'ternary'`, :code:`'2+1'`, :code:`'3'`, :code:`3` triple star setup If :code:`full` or :code:`hierarchical` is not specified, * :code:`'triple'`, :code:`'3'`, and :code:`3` result in *full* code, * :code:`'ternary'` and :code:`'2+1'` results in *hierarchical* code :code:`'quadruple'`, :code:`'quaternary'`, :code:`'qh'`, :code:`'2+1+1'`, :code:`'4'`, :code:`4` quadruple star setup in hierarchical Jacobi coordinates If :code:`full` or :code:`hierarchical` is not specified, * :code:`'quadruple'`, :code:`'4'`, and :code:`4` result in *full* code, * :code:`'quaternary'` and :code:`'2+1+1'` results in *hierarchical* code :code:`'2+2'`, :code:`'2x2'`, :code:`'qp'` quadruple star setup in pair-of-pairs Jacobi coordinates If :code:`full` or :code:`hierarchical` is not specified, use *hierarchical* code by default. :code:`'gw'` quadruple code for gravitational wave studies, pair-of-pairs setup. :code:`'poly'`, :code:`'multi'`, :code:`'polyadic'`, :code:`'multiple'`, :code:`'pf'`, :code:`'n'` full dynamical multi-star code, not yet implemented flags physics flags, usually given as space-separated string for flags (see below) name : string name of model, used in plots comment : string 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. ref : string some references, printed on model setup angles : :code:`'absolote'` | :code:`'relative'` default setting whether angles are absolute or relative data : :code:`'setup'` | :code:`'model'` whether to use object values from *toml* file or from data file path : string global path for data files time : number *time offset* used for star data and GW data (default: 0) objects : list of strings name of sections for objects If not specified, some defaults (to be spelled out here) is used orbits : list of strings name of sections for orbit specifications If not specified, some defaults (to be spelled out here) is used dtmin : number minimum time step of model (s) default is usually 1 tbegin : number start time of run (s) default is 0 This is relative to time offset ``time`` tend : number end time for run (default: 100,000 s) if not specified in run command tmax : number maximum wall clock time (s) for run nstep : number default value for number of steps used by dt : number default value for time to run (s) for :meth:`~multistar.driver.Driver.rund` or default time step for :meth:`~multistar.driver.Driver.runs` dt0 : number default initial (internal) time step (s) for integrator set by :ref:`module ` otherwise, usually 1 for dynamical cases dtd : number default value for minimum time between outputs for :meth:`~multistar.driver.Driver.rund` (s) yscalerf : number Scale factor for reference distance used in integrator for accuracy limit. orientation : bool directive to use body orientations. It sets the flag ``ORI``. Maybe better to just set the ``ORI`` flag directly. quaternion : bool directive to use quaternions for body orientations. It sets the flag ``ORQ``. Maybe better to just set the ``ORQ`` flag directly. eps : number accuracy for integrator (default is :math:`10^{-13}`). cutoff : number | array of numbers distance limit for orbits used as termination condition (cm) interact : scalar | 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) :math:`\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 t0 : number set default zero time for model data and gw data (s); default: 0 Q : number default tidal dissipation quality tau : number default tidal lag time (s) time : number base time for run (s), default is 0 align : bool | ``str`` set default alignment of deformed bodies. See :ref:`orientation_setup`. 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 :code:`config.py`, or specified in the :code:`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 :code:`config.py` and in the :code:`scales` section. All physical values are in *cgs* units by default. Scales ------ In the *optional* :code:`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 :ref:`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 :ref:`config_api` for details. Orbits ------ The names of orbit sections are specified using the :code:`orbits` key of the :ref:`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 :code:`object` coordinates and velocities or explicit orbit descriptions. This is done using the :code:`setup` key setup : :code:`'coord'` | :code:`'orbit'` :code:`'coord'` use *coordinate* mode :code:`'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 r : list of three numbers radius vector (cm) v : list of three numbers velocity vector (cm/s) Instead, one can also specify individual components. This can be more convenient when overwriting values on setup. rx : number x-component of radius vector (cm) ry : number y-component of radius vector (cm) rz : number z-component of radius vector (cm) vx : number x-component of velocity vector (cm/s) vy : number y-component of velocity vector (cm/s) vz : number z-component of velocity vector (cm/s) The phase on the orbit, assuming Keplerian orbital elements, can be set using t : number 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. .. dropdown:: Example: eight.toml .. literalinclude:: ../examples/eight.toml :language: toml 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) euler : array of three numbers Euler angles (rad) (:code:`ascending`, :code:`inclination`, :code:`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 """"""""" gr : bool 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 ^^^^^^^^^^^^^^^^^^^^^^^^ name : ``str`` name of orbit, used in plots :: [orbit] name = 'planet orbit' color : rgb spec color of orbit, used in plots :: color = 'red' color = '#f30000' comment : ``str`` 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 :ref:`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 :ref:`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 :code:`data` value in each object section may be data : ``str`` ``"model"`` select model setup ``"setup"`` select object configuration from TOML file The default value for ``data`` can be set in the :ref:`general_section`. :: data = 'model' If ``data`` is not defined, if an `object` section has the key ``model`` (see :ref:`below `), it defaults to ``"model"`` and to ``"data"`` otherwise (see :ref:`below `). Strictly speaking, it is not needed, maybe of historic origin, but better to specify explicitly for clarity). .. _object_model_data: Setup from model data ^^^^^^^^^^^^^^^^^^^^^ The data is generated from the :code:`str` file from a :doc:`Kepler ` run. The time offset for the model (usually, starting time at :math:`t=0`) is set using the ``t0`` (s) entry. model : ``str`` name of model data file t0 : number zero time for model (s) time : number 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 :ref:`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 .. _object_setup_data: Setup from TOML file ^^^^^^^^^^^^^^^^^^^^ General object parameters """"""""""""""""""""""""" name : ``str`` name of object, used in plots :: [star] name = 'planet orbit' color : rgb spec color of object, used in plots :: color = 'red' color = '#f30000' comment : ``str`` 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 :math:`\times\,\sqrt{1/3}` .. note:: Relations and limits for oblateness and asphericity The moment of inertia tensor diagonal components are proportional to :math:`A = y^2 + z^2` :math:`B = x^2 + z^2` :math:`C = x^2 + y^2` where :math:`x`, :math:`y`, and :math:`z` are the body axis lengths. We then have the relation :math:`A \le B \le C \leftrightarrow z < y < x` With this, *asphericity*, :math:`a`, and oblateness, :math:`o` are defined as :math:`a = \sqrt{(B-A)/C}` :math:`o = 1 - \sqrt{(A+B-C)/C}` Given :math:`a` and :math:`o`, the specific moment normalised of inertia tensor components can be computed as :math:`C = 3\,I / [2 + (1 - o)^2]` :math:`B = C\,[(1-o)^2/4 + a^2/2] + 3/4\,I` :math:`A = 3\,I - B - C` where :math:`I` is the gyration factor, in the literature typically referred to as :math:`k^2` or just :math:`k`. For a sphere, and default here, this is :math:`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 :math:`B < C`, which requires :math:`o \le 1 - \sqrt{1 - a^2}` (limit for prolate solution around Axis A) *Prolate solutions* have :math:`A > C`, which requires :math:`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 (:math:`\mathrm{g}\,\,mathrm{cm}^{-3}`) Moment of inertia """"""""""""""""" I : number | 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, :math:`mathrm{g}\,\mathrm{cm}^2`) if :math:`I \le 1`, assume it is the dimensionless specific gyration radius i : number | 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 :math:`a < 1` assume it is the dimension-less spin-parameter :math:`\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 :math:`r_+`: :math:`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 (:math:`4\,G^2\,M^3\,c^{-4}`) Ig moment of inertia in gravitational units (:math:`G^2\,M^3\,c^{-4}`) .. note:: If neither ``Ig`` nor ``Is`` are provided, compute radius from general spin-dependent formula for :math:`r_+`: :math:`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. :math:`Q_{zz} = -\frac13\, G^2\,M\,a^2\,c^{-4}` :math:`Q_{xx} = Q_{yy} = -\frac12\, Q_{zz}` and we should use :math:`I_{zz} = 2\, G^2\,c^{-4}\,M^2\,\left(M + \sqrt{M^2 - a^2}\right)` :math:`I_{xx} = I_{yy} = I_{zz} - G^2\,M\,a^2\,c^{-4}` where we use our definition for :math:`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 :code:`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) :math:`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) reference : ``str`` 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_setup: 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. orientation : number | 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) orienteuler : list 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 align : ``str`` | ``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 :code:`[[gw]]` for each section. Keys are name : string name of GW source component mode : :code:`'strain'` | :code:`'amplitude'` | :code:`'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 :code:`M1` and :code:`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 :code:`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: Config API ---------- This API can be used to modify the TOML file before generating a :code:`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 :code:`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 :code:`del` intrinsic or by assigning :code:`None`. Non-existing keys can be added using the :meth:`multistar.config.Config.set` method explicitly: :: toml.set('Star A.diameter_km', 5.e8) Sections, called *tables* in TOML documentation, can be added using :meth:`multistar.config.Config.addtable` :: toml.addtable('star 1') Arrays of sections, called *arrays* in TOML documentation, can be added using :meth:`multistar.config.Config.addarray`, new array entries can be added using :meth:`multistar.config.Config.addarrayitem` and array entries can be deleted using :meth:`multistar.config.Config.delarrayitem`. :: toml.addarray('stars', n=3) Starting with :meth:`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 :code:`scales` special section lead to updated evaluation of the values, in order as defined in the TOML file. The optional :code:`pos` argument to the :code:`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 :code:`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 :code:`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 ^^^^^^^ .. automethod:: multistar.config.Config.__init__ .. automethod:: multistar.config.Config.new .. automethod:: multistar.config.Config.addtable .. automethod:: multistar.config.Config.addarray .. automethod:: multistar.config.Config.addarrayitem .. automethod:: multistar.config.Config.delarrayitem .. automethod:: multistar.config.Config.set .. automethod:: multistar.config.Config.setarr .. automethod:: multistar.config.Config.update .. automethod:: multistar.config.Config.updated .. automethod:: multistar.config.Config.delete .. automethod:: multistar.config.Config.get .. automethod:: multistar.config.Config.value .. automethod:: multistar.config.Config.write .. automethod:: multistar.config.Config.print .. automethod:: multistar.config.Config.copy .. automethod:: multistar.config.Config.compare .. automethod:: multistar.config.Config.get_config_entry .. automethod:: multistar.config.Config.get_config_value .. automethod:: multistar.config.Config.haskey .. automethod:: multistar.config.Config.isscalar .. automethod:: multistar.config.Config.istable .. automethod:: multistar.config.Config.isarray .. automethod:: multistar.config.Config.keys .. automethod:: multistar.config.Config.values .. automethod:: multistar.config.Config.items .. automethod:: multistar.config.Config.subkeys .. automethod:: multistar.config.Config.subitems .. automethod:: multistar.config.Config.subvalues .. automethod:: multistar.config.Config.subitemsdict .. automethod:: multistar.config.Config.sectionkeys .. automethod:: multistar.config.Config.sectionitems .. automethod:: multistar.config.Config.sectionvalues .. automethod:: multistar.config.Config.sections .. automethod:: multistar.config.Config.__or__ Default scales (units) ^^^^^^^^^^^^^^^^^^^^^^ s 1. cm 1. g 1. Hz 1. 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 3600. hour 3600. min, minute 60. 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