Data access methods and properties

By default, run variables have the format [object, time, dimension(s)].

• For scalar quantities, such as distance magnitude, there is no dimension coordinate(s).

• For general quantities, such as time, or for select quantities returned by some methods, there is no object coordinate.

• Some quantities, such as quadrupole tensor, may have two dimensions. Often, these quantities will be named with a double letter.

• Some quantities, such as names, may have only an object coordinate.

Some quantities that require no options and that are fast to compute are returned as attributes. Some attributes are also cached, so access is fast.

Setup attributes

These are set in the setup routine of SetupBase.

Stellar data

stardata

time-dependent stellar properties, as loaded from data files, or set in configuration file if constant.

Todo

Allow to embed data into TOML file.

stars_t0

zero-time of stardata, for each star (s)

stardatafiles

names of data files used, if any

Configuration data

name

name of setup, as set in configuration

stars

list of star objects, containing initial object properties

hierarchy

object hierarchy of (initial) Jacobi configuration

time

time offset of t array (see below) relative to zero-time of stellar data (stars_t0). (s)

General

Attributes

nstar

number of stars

norb

number of orbits

nstar-1

t

time (s)

Note

The actual physical time is t + time.

y

solution vector(s)

Note

The attributes t and y only hold the initial values directly after setup.

Note

The corresponding stellar data time is computed from t by adding the run time offset, time, and zero-time for each star, stars_t0.

The attributes and properties below return the interpolated data that correspond to the run times in t.

Properties

property OrbitBase.dt

time steps (s)

property OrbitBase.tt

total time (s)

tt = t + time

property OrbitBase.norbit

number of orbits

property OrbitBase.orbit_names

names of orbits

property OrbitBase.orbit_masses

total masses of orbits (g)

property OrbitBase.mo

mass in each orbit (g)

property OrbitBase.orbits

list of orbits (Orbit objects)

property OrbitBase.names

star names (string)

deprecated, use star_names

property OrbitBase.star_names

star names - seems identical to just ‘names’ property (string)

Driver

Some attributes are set in the driver class.

property Driver.shadow

shadow configuration namespace object

property Driver.nshadow

return number of shadows

property Driver.ndim

dimension of shadow runs.

\(0\) if no shadow is defined (result is “scalar”) and \(1\) otherwise.

For Numpy interface compatibility.

property Driver.shape

shape of shadow runs.

() if no shadow is defined (result is “scalar”) and length-one tuple otherwise (one plus number of shadows).

For Numpy interface compatibility.

status

numerical run status flag

property Driver.status_name: str

name of status as string

status_stars

array of stars causing termination

status_shadow

shadow image (1-based index) causing termination

property Driver.version

driver version number

Objects

Properties

property OrbitBase.m

stellar masses (g)

property OrbitBase.R

stellar radii (cm)

property OrbitBase.s

stellar radii (cm)

Same as R

Used for historical reasons based on Mardling & Lin (2002).

TODO

remove

property OrbitBase.k

apsidal motion constant

property OrbitBase.tau

tidal lag time (s)

Returns None where undefined, e.g., if Q is used instead.

property OrbitBase.Q

quality orbital motion due to tidal friction

Returns None where undefined, e.g., if tau is used instead.

This quantity makes no sense outside binaries or hierarchical motions.

property OrbitBase.kt

apsidal motion constant / tidal lag time (1/s)

property OrbitBase.s5k

apsidal motion factor S**5 * k (cm**5)

property OrbitBase.i

moment of inertia of stars (g*cm**2)

raw value from data file

TODO

It probably would be better to switch i_ and i, such that the (internal) raw values is i_.

Note

Raw format of moment of inertial is to only set the z component to non-zero value for scalar moment of inertia (spherically symmetric body).

TODO

Equally possible would be to set the z component to a negative value, saves on tests (only test one quantity for being negative), but adds a floating point operation (invert sign).

Maybe it would be easier to just set all components to equal values, should be save enough and also requires only two tests.

property OrbitBase.ix

x-compnent of moment of inertia of stars (g*cm**2)

raw value from data file

property OrbitBase.iy

y-compnent of moment of inertia of stars (g*cm**2)

raw value from data file

property OrbitBase.iz

z-compnent of moment of inertia of stars (g*cm**2)

raw value from data file

property OrbitBase.i_

moment of inertia of stars, corrected diagonal (g*cm**2)

property OrbitBase.ix_

x-component of corrected moment of inertia of stars (g*cm**2)

property OrbitBase.iy_

y-component of corrected moment of inertia of stars (g*cm**2)

property OrbitBase.iz_

z-component of corrected moment of inertia of stars (g*cm**2)

property OrbitBase.ii_

non-rotated moment of intertia tensor (g*cm**2)

property OrbitBase.ii

rotated moment of intertia tensor (g*cm**2)

property OrbitBase.iii

inverse of the moment of intertia tensor (g**(-1)*cm**(-2))

property OrbitBase.q

quadrupole tensor of stars (g*cm**2)

diagonal of tensor in normal form

property OrbitBase.qq

rotated quadrupole tensor of stars (g*cm**2)

property OrbitBase.qq_

rotated quadrupole tensor of stars (g*cm**2)

alternative version - always good to check

property OrbitBase.axes

‘semi’ axes of body (cm)

property OrbitBase.dims

dimensions of body (cm)

These should be in oder of decreasing size.

property OrbitBase.j

angular momentum vector of stars (erg*s)

property OrbitBase.jn

angular momentum magnitude of stars (erg*s)

property OrbitBase.je

angular momentum unit vector of stars (1)

property OrbitBase.w

angular velocity vector of stars (rad/s)

property OrbitBase.wn

angular velocity magnitude of stars (rad/s)

property OrbitBase.we

angular velocity unit vector of stars (1)

property OrbitBase.wabc

angular velocity vector of stars in body frame (rad/s)

For bodies with no permanant quadruple moment, rotation about the z axis is assumed.

property OrbitBase.P

rotation period of stars (s)

property OrbitBase.erot

rotational energy of stars (erg)

property OrbitBase.f

orientaion quaternion (1)

property OrbitBase.fdot

rate of change of the orientaion quaternion (1/s)

property OrbitBase.fdotabc

rate of change of the orientaion quaternion in body frame (1/s)

property OrbitBase.o

orientation rotation vector (rad)

property OrbitBase.on

norm of orientation rotation vector (rad)

property OrbitBase.odot

rate of change of orientaion vector (1/s)

This approach diverges as reconstracted omega approaches length of 2 pi. we could normalise the quaternion to corespond to a smaller w, presumably f0 > 0. This would need to go in sync in limiting the orientation vector returned to a magnitude of pi. Things would still jump, but at each point one can define a derivative that is not diverging.

Quaternions are the way to go.

where f0 < 0, swap

property OrbitBase.A

orientation rotation matrix of stars (1)

property OrbitBase.e

Euler angles (rad)

Note that there are degeneracies for rotations about the z axis and any rotation by pi in the x-y-plane.

TODO - reconstruction of orientations in x-y-plane

property OrbitBase.edot

rate of change of Euler angles in ZXZ form (rad/s)

Beware that there are degeneracies in the Euler angles.

Currently we introduce some “eps” to get rid of infinities and negative square root due to numerical inaccuracy, however, thesw cases do not yield useful results, and one may want to set self.eps_edot = 0

if e_2 == 0, 180 (f_1 == f_2 == 0)

do reconstruction just for e_1, e_2, set e_3 to 0

TODO - reconstruction if w != w_z

TODO - reconstruction if f_0 == f_3 == 0

Generic methods

OrbitBase.Qo(star, orbit=None)

return quality of orbit for given star, based on tau

OrbitBase.phase_lag(star, orbit=None)

return phase lag angle (eps) of orbit for given star, based on tau (rad)

Stability analysis

OrbitBase.jacobian(var=None, i=Ellipsis, *, eps=1e-07, yscale=None)

return Jacobian matrix of orbital elements

variables are position vectors, velocities, angular momenta, orientation

var

None

compute full jacobian

‘orbit’

only use orbit components

‘orbit_xy’

only use orbit xy components

‘dyn’

only use non-trivial Newtonian dynamics

‘dyn_xy’

only use non-trivial Newtonian dynamics xy components

‘spin’

only use spin/orientation components

‘spin_z’

only use z components

cannot work when orientation is used and provided as quaternion (default)

‘xy’

only use xy components of orbit, and z-component of spin/orientation

cannot work when orientation is used and provided as quaternion (default)

int

use first var values

slice

use these indices

list or tuple or np.ndarray of ints

use these indices

i

Ellipsis

return all values (default)

None

return last value

int

return value at this index

ndarray(int)

return data at these indices

eps

float

variation used for numerical derivative, relative to self.yscale

vector of floats

use these; dimension needs to mach number of variables

yscale

use this instead of self.yscale

dimensions need to match self.yscale or jacobian

General dynamic (direct) driver

Properties

property DirectBase.r

radius vector relative to center of mass (cm)

property DirectBase.rn

radius magnitude relative to center of mass (cm)

property DirectBase.v

velocity vector relative to center of mass (cm/s)

property DirectBase.vn

velocity magnitude relative to center of mass (cm/s)

property DirectBase.acc

acceleration vector relative to center of mass (cm/s^2)

property DirectBase.accn

acceleration magnitude relative to center of mass (cm/s^2)

property DirectBase.ro

radius vector of orbits (cm)

property DirectBase.rno

radius magnitude of orbits (cm)

property DirectBase.vo

velocity vector of orbits (cm/s)

property DirectBase.vno

velocity magnitude of orbits (cm/s)

property DirectBase.acco

acceleration vector of orbits (cm/s^2)

property DirectBase.accno

acceleration magnitude of orbits (cm/s^2)

property DirectBase.vro

radial velocity of orbits (cm/s)

property DirectBase.jo

angular momentum vectors of orbits (erg s)

property DirectBase.jno

angular momentum mantudes of orbits (erg s)

property DirectBase.h

specific angular momentum vector of orbits (erg s / g)

\(h/\mu\)

property DirectBase.hn

specific angular momentum magnitude of orbits (erg s / g)

\(h/\mu\)

property DirectBase.jt

total angular momentum of system (erg s)

Defines the invarant plane of the system

property DirectBase.inc

inclination of orbits relative to normal of invaraint plane (rad)

property DirectBase.obliquity

obliquity of object relative to its closest orbit (rad)

property DirectBase.oblt

obliquity of star relative to system total angular momemntum (rad)

The system total angular momentum defines the ‘invariante plane’.

property DirectBase.wo

orbital angular velocity vector of orbits (rad/s)

mean motion

assume Keplerian orbit elements as deduced from current (r,v) assuming hierarchical system configuration

Note - does not allow elim

property DirectBase.wno

orbital angular velocity magnitude of orbits (rad/s)

mean motion

Note - does not allow elim

property DirectBase.Po

orbital period of orbits (s)

period of mean motion

property DirectBase.woi

instantaneous angular velocity vector of orbits (rad/s)

Note that this is not the same as reconstructed Keplerian mean motion vector.

property DirectBase.wnoi

instantaneous angular velocity magnitude of orbits (rad/s)

Note that this is not the same as reconstructed Keplerian mean motion.

property DirectBase.Poi

instantaneous orbital period of orbits (s)

Note that this is not the same as reconstructed Keplerian mean motion period.

property DirectBase.jc

angular momenta of stars relative to center of mass (erg s)

property DirectBase.p

stellar momenta (g*cm/s)

property DirectBase.pn

stellar momenta magnitide (g*cm/s)

property DirectBase.ekin

kinetic energy (erg)

property DirectBase.mu

orbital reduced masses (g)

property DirectBase.n

orbit mean motion

TODO - seems same as wno

Note - does not allow elim

Methods

Parameter types for data methods

stars

star name, index, or tuple thereof.

i

time slice index

t

time for time slice (s)

elim

limit for when 1 - eccentricity is considered a parabolic orbit

Data methods

DirectBase.dr(stars1, stars2, i=None, t=None)

return center of mass distance vector (cm)

DirectBase.drn(*args, **kwargs)

return center of mass distance (cm)

same parameters as dr.

DirectBase.dv(stars1, stars2, i=None, t=None)

return center of mass relative velocity vector (cm/s)

DirectBase.dvn(*args, **kwargs)

return center of mass relative velocity magnitude (cm/s)

same parameters as dv.

DirectBase.r_cms(stars=None, i=None, t=None)

return center of mass coordinate vector (cm)

DirectBase.rn_cms(*args, **kwargs)

return center of mass coordinate vector magnitude (cm)

same parameters as r_cms.

DirectBase.v_cms(stars=None, i=None, t=None)

return center of mass velocity vector (cm/s)

DirectBase.vn_cms(*args, **kwargs)

return center of mass velocity magnitude (cm/s)

same parameters as v_cms.

DirectBase.rvm(stars1, stars2, i=None, t=None)

return r (cm), v (cm/s), m (g) for two groups of stars

DirectBase.aben(*args, return_omega=False, elim=None, **kwargs)

return semimajor axis (cm), semiminor axis (cm), and eccentricity for pair of groups of stars at indices (kw i) or times (kw t)

default is end of run

uses same positional and keyword arguments as rvm

DirectBase.anen(*args, **kwargs)

return an (cm), en for groups of stars

uses same positional and keyword arguments as aben

DirectBase.rp(*args, **kwargs)

return periapsis distance for groups of stars (cm)

uses same positional and keyword arguments as aben

DirectBase.ra(*args, **kwargs)

return apoapsis distance for groups of stars (cm)

yields:

• nan for parabolic orbits

• inf for hyperbolic orbits

uses same positional and keyword arguments as aben

DirectBase.a(*args, **kwargs)

return a for groups of stars (cm)

semi-major axis in direction of rp

uses same positional and keyword arguments as aben

DirectBase.an(*args, **kwargs)

return an for groups of stars (cm)

semimajor axis length

uses same positional and keyword arguments as aben

DirectBase.b(*args, **kwargs)

return b for groups of stars (cm)

semi-minor axis in direction j x a

uses same positional and keyword arguments as aben

DirectBase.bn(*args, **kwargs)

return bn for groups of stars (cm)

semi-minor axis length

uses same positional and keyword arguments as aben

DirectBase.en(*args, **kwargs)

return en for groups of stars

Parameters:

Uses same positional and keyword arguments as :code:`aben`

Note

This is not the norm of the e property, which returns the Euler angles of an object’s orientation.

DirectBase.Pg(*args, **kwargs)

return orbital period for groups of stars

uses same positional and keyword arguments as aben

DirectBase.anomaly(*args, **kwargs)

return true anomaly, f, for groups of stars (rad)

uses same positional and keyword arguments as rvm

DirectBase.mean(*args, **kwargs)

return mean anomaly, M, for groups of stars (rad)

uses same positional and keyword arguments as rvm

DirectBase.eccentric(*args, **kwargs)

return eccentric anomaly, E, for groups of stars (rad)

uses same positional and keyword arguments as rvm

DirectBase.vperi(*args, **kwargs)

return velicity at periapsis for groups of stars (cm/s)

uses same positional and keyword arguments as rvm

DirectBase.vapo(*args, **kwargs)

return velicity at apoapsis or infinity for groups of stars

uses same positional and keyword arguments as rvm

DirectBase.abeno(iorb=None, i=None, t=None, elim=None)

return semimajor axis vector (cm), semiminor axis vector (cm), and numerical eccentricity (scalar) for orbit iorb

Parameters:

• iorb (int) – index or orbits (required if more than one orbit in system)

• i (int) – index of time slice

• t (float) – time of slice

Note

Provide at most one of t and i. If neither is provided, values for the entrie run are computed.

Returns:

• semimajor axis vector (cm),

• semiminor axis vector (cm),

• and numerical eccentricity (scalar)

• (TODO - is this still true (*)*)

• by default, values are given for end of run

DirectBase.ao(*args, **kwargs)

return semi-major axis vector (cm)

see abeno for details

DirectBase.bo(*args, **kwargs)

return semi-minor axis vector (cm)

see abeno for details

DirectBase.eo(*args, **kwargs)

return Runge Lenz vector

see abeno for details

DirectBase.aneno(*args, **kwargs)

return length of semi-major axis (cm) and eccentricity

see abeno for details

DirectBase.ano(*args, **kwargs)

return length of semi-major axis (cm)

see abeno for details

DirectBase.bno(*args, **kwargs)

return length of semi-minor axis (cm)

see abeno for details

DirectBase.eno(*args, **kwargs)

return numerical eccentricity

see abeno for details

DirectBase.Ao(*args, **kwargs)

return rotation matrix of orbit

see abeno for details

TODO - check whether this is forward or reverse, i.e., whether

last two axes need to be flipped

DirectBase.rpo(*args, **kwargs)

return periapsis distance (cm)

see abeno for details

DirectBase.rao(*args, **kwargs)

return apoapsis distance (cm)

yields:

• nan for parabolic orbits

• inf for hyperbolic orbits

see abeno for details

DirectBase.anrpo(*args, **kwargs)

return semi-major axis length (cm) and periapsis distance (cm)

see abeno for details

Operational effective values for non-keplerian orbits

DirectBase.effenwn(stars1, stars2)

return effective eccentricity and mean motion for groups of stars

DirectBase.effwn(*args, **kwargs)

return effective mean motion for groups of stars

see effenwn

DirectBase.effen(*args, **kwargs)

return effective eccentricity for groups of stars

see effenwn

DirectBase.effP(*args, **kwargs)

return effective mean period for groups of stars

see effenwn

DirectBase.effenwno(iorb)

return effective eccentrictiy and mean motion for orbit iorb

DirectBase.effwno(*args, **kwargs)

return effective mean motion for orbits

see effenwno

DirectBase.effeno(*args, **kwargs)

return effective eccentricity for orbits

see effenwno

DirectBase.effPo(*args, **kwargs)

return effective mean period for orbits

see effenwno

Sidereal and synodic values

DirectBase.Psyn(iorb1=None, iorb2=None, mode='center', fast=True)

return synodic period of orbit (s)

Parameters:

• iorb1, iorb2 (int | str) – indices or names of orbits (required)

• mode (string) –

  'final'

  period of orbit before current time

  'initial'

  period of orbit after current time

  'center'

  period of orbit +/- pi angle (default)

• fast (bool) –

  True

  use NumPy version (default)

  False

  use slower Python version

  The NumPy version may be less accuate due to numerical round-off for large integrated total phase.

Returns:

• *NumPy array of synodic periods between the two orbits,*

• np.nan where not defined due to simulation domain

• bounds.

Note

The motion may include epicycles.

TODO

add ‘virual’ orbits for any pairs of groups of objects

TODO

add version that adjusts reference diretion for each data point. This needs to be constant thoughout the calculation of that data point, so a lot more calculations may need to be done.

DirectBase.wsyn(*args, **kwargs)

return synodic angular velocity

see Psun for details

DirectBase.Psid(iorb=0, mode='center', fast=True)

return sidereal period of orbit (s)

Parameters:

• iorb (int | str) – index or name of orbit (required)

• mode (string) –

  'final'

  period of orbit before current time

  'initial'

  period of orbit after current time

  'center'

  period of orbit +/- pi angle (default)

• fast (bool) –

  True

  use NumPy version (default)

  False

  use slower Python version

  The NumPy version may be less accuate due to numerical round-off for large integrated total phase.

Returns:

• *NumPy* array of sidereal periods, np.nan where not

• defined due to simulation domain bounds.

TODO

add ‘virual’ orbits for any pairs of groups of objects

TODO

add version that adjusts reference diretion for each data point. This needs to be constant thoughout the calculation of that data point, so a lot more calculations may need to be done.

DirectBase.wsid(*args, **kwargs)

return sidereal angular velocity

see Psid for details

DirectBase.arc(iorb)

return total angle of orbit on unit sphere (rad)

Parameters:

iorb (int | str) – index or name of orbit (required)

Returns:

• *NumPy array of arc on unit sphere.*

• For motion in a plane, this is equivalent to the total phase.

DirectBase.arc_rel(iorb1, iorb2)

return total angle of relative motion of two orbits on the unit sphere (rad)

Parameters:

iorb1, iorb2 (int | str) – indeices or names of orbits (required)

Returns:

• *NumPy array of arc on unit sphere.*

• For motion in a plane, this is equivalent to the total phase.

Orbital elements

DirectBase.aeiwWfo(iorb=None, i=None, t=None, elim=None)

orbit an, en, i, w, W, f

an - semimajor axis en - eccentricity i - inclination w - argument of periapsis W - longitude of ascending node f - anomaly - true anomaly (angle from perapis relative to focal point)

GW signal

property DirectBase.gw

external gw data array [h_ij, d/dt h_ij, 1/2 * d^2/dt^2 h_ij, w, phase]

units

h_ij (1)

d/dt h_ij (rad/s)

s^2/dt^2 h_j (rad^2/s^2)

w (rad/s)

phase (rad)

property DirectBase.gww

gw angular velocity (rad/s)

property DirectBase.gwp

gw phase (rad)

property DirectBase.gwhh

strain tensor h_ij

property DirectBase.gwhh1

first derivative of strain tensor, d/dt h_ij (rad/s)

property DirectBase.gwhh2

second derivative of strain tensor, d^2/dt^2 h_ij (rad^2/s^2)

property DirectBase.gwhhap

strain tensor amplitude and phase

property DirectBase.gwhha

(reconstruced) strain tensor h_ij amplitude

property DirectBase.gwha

strain amplitude

This may only work for circular orbits

property DirectBase.gwtheta

phase angle theta (rad)

property DirectBase.ngw

number of gw sources

property DirectBase.gwname

names of gw sources

property DirectBase.gwacc

acceleration due to gw strain (cm/s^2)

property DirectBase.gwnear

external nearfield relative acceleration tensor [NaN*18, d^2/dt^2 H_ij, w, phase]

units

H (rad^2/s^2)

w (rad/s)

phase (rad)

property DirectBase.gwnearhh2

nearfield acceleration tensor

d^2/dt^2 H_ij (rad^2/s^2)

property DirectBase.gwnearw

nearfield gw angular velocity (rad/s)

property DirectBase.gwnearp

nearfield gw phase (rad)

property DirectBase.gwqq

external quadrupole tensor [qq0, qq1, qq2, qq3, qq4, w]

units

qq0 (g cm^2)

qq1 (g cm^2 rad/s)

qq2 (g cm^2 rad^2/s^2)

qq3 (g cm^2 rad^3/s^3)

qq4 (g cm^2 rad^4/s^4)

w (rad/s)

property DirectBase.gwqq0

quadrupole tensor

qq0 (g cm^2)

property DirectBase.gwqq1

first derivative of quadrupole tensor

qq1 (g cm^2 rad/s)

property DirectBase.gwqq2

second derivative of quadrupole tensor

qq2 (g cm^2 rad^2/s^2)

property DirectBase.gwqq3

third derivative of quadrupole tensor

qq3 (g cm^2 rad^3/s^3)

property DirectBase.gwqq4

forth derivative of quadrupole tensor

qq4 (g cm^2 rad^4/s^4)

property DirectBase.gwqqw

qq angular velocity (rad/s)

Collision data

property DirectBase.collision

collision properties (object)

Binary direct driver (Direct2)

Methods

Direct2.jGR(r, v, m, m12, mu, mm1, j, j1, j2, order=None, so=None)

compute GR-corrected angular momentum

Secular driver (Secular2)

Properties

property Secular2.h

orbit specific angular momentum, h/mu (erg*s/g)

property Secular2.hn

orbit specific angular momentum magnitude, h/mu (erg*s/g)

property Secular2.h1

orbit specific angular momentum of inner (only) orbit, h/mu (erg*s/g)

property Secular2.e

orbit eccentricity

property Secular2.en

orbit numerical eccentricity

Norm of Runge-Lenz vector

property Secular2.e1

orbit eccentricity of inner orbit

property Secular2.j1

angular momentum of first star (erg*s)

property Secular2.j2

angular momentum of second star (erg*s)

property Secular2.n

orbit angular velocity (rad/sec)

same as wno

property Secular2.wo

orbit angular velocity vector (rad/sec)

property Secular2.wno

orbit angular velocity (rad/sec)

property Secular2.Po

orbit period (sec)

property Secular2.M

system total mass (g)

property Secular2.an

orbit semimajor axis (cm)