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.

General#

Attributes#

t

time (s)

y

solution vector(s)

nstar

number of stars

norb

number of orbits

nstar-1

Properties#

property OrbitBase.dt#

time steps (s)

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)

deperecated, use star_names

property OrbitBase.star_names#

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

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.w#

angular velocity vector of stars (rad/s)

property OrbitBase.wn#

angular velocity magnitude of stars (rad/s)

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 - reconstructin 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)

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)

property DirectBase.vn#

velocity magnitude relative to center of mass (cm)

property DirectBase.ro#

radius vector of orbits (cm)

property DirectBase.ron#

radius magnitude of orbits (cm)

property DirectBase.vo#

velocity vector of orbits (cm/s)

property DirectBase.von#

velocity magnitude of orbits (cm/s)

property DirectBase.vro#

radial velocity of orbits (cm/s)

property DirectBase.jo#

angular momentum vectors of orbits (erg s)

property DirectBase.jon#

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.won#

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)

property DirectBase.woin#

instantaneous angular velocity magnitude of orbits (rad/s)

property DirectBase.Poi#

instantaneous orbital period of orbits (s)

property DirectBase.jc#

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

property DirectBase.p#

stellar momenta (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 won

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

uses same positional and keyword arguments as aben

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

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)#

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)#

effective eccentricity and mean motion for groups of stars

DirectBase.effwn(*args, **kwargs)#

effective mean motion for groups of stars

see effenwn

DirectBase.effen(*args, **kwargs)#

effective eccentricity for groups of stars

see effenwn

DirectBase.effP(*args, **kwargs)#

effective mean period for groups of stars

see effenwn

DirectBase.effenwno(iorb)#

effective eccentrictiy and mean motion for orbit iorb

DirectBase.effwno(*args, **kwargs)#

effective mean motion for orbits

see effenwno

DirectBase.effeno(*args, **kwargs)#

effective eccentricity for orbits

see effenwno

DirectBase.effPo(*args, **kwargs)#

effective mean period for orbits

see effenwno

Sidereal and synodic values#

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

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.

  • TODO - add ‘virual’ orbits for any pairs of groups of objects

DirectBase.wsyn(*args, **kwargs)#

synodic angular velocity

see Psun for details

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

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

DirectBase.wsid(*args, **kwargs)#

sidereal angular velocity

see Psid for details

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 won

property Secular2.wo#

orbit angular velocity vector (rad/sec)

property Secular2.won#

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)

On this page

This Page