Orbits

If they represent binary or triple star systems, vespa.stars.StarPopulation objects are created with a large population of randomized orbits. This is done using the OrbitPopulation and TripleOrbitPopulation objects.

The engine that makes it possible to initialize large numbers of random orbital positions nearly instantaneously is the kepler.Efn() function (as used by utils.orbit_posvel()), which uses a precomputed grid to interpolate the solutions to Kepler’s equation for a given mean anomaly and eccentricity (or arrays thereof).

The final coordinate system of these populations is “observer-oriented,” with the z axis along the line of sight, and the x-y plane being the plane of the sky. Practically, this is accomplished by first simulating all the random orbits in the x-y plane, and then “observing” them from lines of sight randomly oriented on the unit sphere, and projecting appropriately.

Coordinates are handled using astropy.coordinates.SkyCoord objects.

Orbit Populations

class vespa.orbits.populations.OrbitPopulation(M1, M2, P, ecc=0, n=None, mean_anomaly=None, obsx=None, obsy=None, obsz=None, obspos=None)

Population of orbits.

Parameters:

• M1,M2 – Primary and secondary masses (if not Quantity, assumed to be in solar masses). Can be float, array-like or Quantity.
• P (float, array-like or Quantity.) – Orbital period(s) (if not Quantity, assumed to be in days)
• ecc – (float or array-like, optional) Eccentricities.
• n – (optional) Number of instances to simulate. If not provided, then this number will be the length of M2 (or P) provided.
• mean_anomaly – (optional) Mean anomalies of orbits. Usually this will just be set randomly, but can be provided to initialize a particular state (e.g., when restoring an OrbitPopulation object from a saved state).
• obsy, obsz (obsx,) – (optional) “Observer” positions to define coordinates. Will be set randomly if not provided.
• obspos (astropy.coordinates.SkyCoord) – (optional) “Observer” positions may be set with a SkyCoord object (replaces obsx, obsy, obsz)

RV

Relative radial velocities of two stars

RV_com1

RVs of star 1 relative to center-of-mass

RV_com2

RVs of star 2 relative to center-of-mass

RV_timeseries(ts, recalc=False)

Radial Velocity time series for star 1 at given times ts.

Parameters:

• ts (array-like or Quantity) – Times. If not Quantity, assumed to be in days.
• recalc – (optional) If False, then if called with the exact same ts as last call, it will return cached calculation.

Rsky

Sky separation of stars, in projected AU.

dRV(dt, com=False)

Change in RV of star 1 for time separation dt (default=days)

Parameters:

• dt (float, array-like, or Quantity) – Time separation for which to compute RV change. If not a Quantity, then assumed to be in days.
• com – (bool, optional) If True, then return dRV of star 1 in center-of-mass frame.

Return dRV:

Change in radial velocity over time dt.

dataframe

Summary DataFrame of OrbitPopulation

Used to save/restore state.

classmethod from_df(df)

Creates an OrbitPopulation from a DataFrame.

Parameters:df – pandas.DataFrame object. Must contain the following columns: ['M1','M2','P','ecc','mean_anomaly','obsx','obsy','obsz'], i.e., as what is accessed via OrbitPopulation.dataframe. Returns:OrbitPopulation.

classmethod load_hdf(filename, path='')

Loads OrbitPopulation from HDF file.

Parameters:

• filename – HDF file
• path – Path within HDF file store where OrbitPopulation is saved.

save_hdf(filename, path='')

Saves all relevant data to .h5 file; so state can be restored.

scatterplot(fig=None, figsize=(7, 7), ms=0.5, rmax=None, log=False, **kwargs)

Makes a scatter plot of projected X-Y sky separation

Parameters:

• fig – (optional) Passed to plotutils.setfig()
• figsize – (optional) Size of figure (in).
• ms – (optional) Marker size
• rmax – (optional) Maximum projected radius to plot.
• log – (optional) Whether to plot with log scale.
• **kwargs –

  Additional keyword arguments passed to plt.plot.

class vespa.orbits.populations.TripleOrbitPopulation(M1, M2, M3, Plong, Pshort, ecclong=0, eccshort=0, n=None, mean_anomaly_long=None, obsx_long=None, obsy_long=None, obsz_long=None, obspos_long=None, mean_anomaly_short=None, obsx_short=None, obsy_short=None, obsz_short=None, obspos_short=None)

Stars 2 and 3 orbit each other (short orbit), far from star 1 (long orbit)

This object defines the orbits of a triple star system, with orbits calculated assuming the “long” orbit does not perturb the “short” orbit, which will not be true in the long run, but should be true over short timescales as long as Plong >> Pshort.

A TripleOrbitPopulation is essentially made up of two OrbitPopulation objects: one for the “long” orbit and one for the “short.”

Parameters:

• M1,M2,M3 – Masses of stars. Stars 2 and 3 are in a short orbit, far away from star 1. If not astropy.units.Quantity objects, then assumed to be in solar mass units. May be single value or array-like.
• Plong,Pshort – Orbital Periods. Plong is orbital period of 2+3 and 1; Pshort is orbital period of 2 and 3. If not astropy.units.Quantity objects, assumed to be in days. Can be single value or array-like. N.B. If any item in Pshort happens to be longer than the corresponding item in Plong, they will be switched.
• ecclong,eccshort – (optional) Eccentricities. Same story (long vs. short). Default=0 (circular). Can be single value or array-like.
• n – (optional) Number of systems to simulate (if M1, M2, M3 aren’t arrays of size > 1 already).
• mean_anomaly_short,mean_anomaly_long – (optional) Mean anomalies. This is only passed if you need to restore a particular specific configuration (i.e., a particular saved simulation), e.g., as done by TripleOrbitPopulation.from_df(). If not provided, then randomized on (0, 2pi).
• obsx_short,obsy_short,obsz_short – (optional) “Observer” positions for the short orbit. Also only passed for purposes of restoring configuration.
• obsx_long,obsy_long,obsz_long – (optional) “Observer” positions for long orbit. Also only passed for purposes of restoring configuration.
• obspos_short,obspos_long – (optional) “Observer positions for short and long orbits, provided as astropy.SkyCoord objects. These will replace obsx_short/long, obsy_short/long, obsz_short/long parameters if present.

RV

Instantaneous RV of star 1 with respect to system center-of-mass

RV_1

Instantaneous RV of star 1 with respect to system center-of-mass

RV_2

Instantaneous RV of star 2 with respect to system center-of-mass

RV_3

Instantaneous RV of star 3 with respect to system center-of-mass

Rsky

Projected separation of star 2+3 pair from star 1 [projected AU]

dRV(dt)

Returns difference in RVs (separated by time dt) of star 1.

Parameters:dt – Time separation for which to compute RV change. If not an astropy.units.Quantity object, then assumed to be in days.

dRV_1(dt)

Returns difference in RVs (separated by time dt) of star 1.

Parameters:dt – Time separation for which to compute RV change. If not an astropy.units.Quantity object, then assumed to be in days.

dRV_2(dt)

Returns difference in RVs (separated by time dt) of star 2.

Parameters:dt – Time separation for which to compute RV change. If not an astropy.units.Quantity object, then assumed to be in days.

dRV_3(dt)

Returns difference in RVs (separated by time dt) of star 3.

Parameters:dt – Time separation for which to compute RV change. If not an astropy.units.Quantity object, then assumed to be in days.

classmethod from_df(df_long, df_short)

Builds TripleOrbitPopulation from DataFrame

DataFrame objects must be of appropriate form to pass to OrbitPopulation.from_df().

Parameters:df_short (df_long,) – pandas.DataFrame objects to pass to OrbitPopulation.from_df().

classmethod load_hdf(filename, path='')

Load TripleOrbitPopulation from saved .h5 file.

Parameters:

• filename – HDF file name.
• path – Path within HDF file where data is stored.

save_hdf(filename, path='')

Save to HDF5 file in desired path.

Utility Functions

The following functions are used in the creation of OrbitPopulation objects. kepler.Efn() is used for instanteous solution of Kepler’s equation (via interpolation), and utils.orbit_posvel() does the projecting of random orbits into 3-d Cartesian coordinates, assisted by utils.orbitproject() and utils.random_spherepos().

vespa.orbits.kepler.Efn(Ms, eccs)

Returns Eccentric anomaly, interpolated from pre-computed grid of M, ecc

Instantaneous solution of Kepler’s equation!

Works for -2*np.pi < Ms < 2*np.pi and eccs <= 0.97

Parameters:

• Ms – (float or array-like) Mean anomaly
• eccs – (float or array-like)

vespa.orbits.utils.orbit_posvel(Ms, eccs, semimajors, mreds, obspos=None)

Returns positions in projected AU and velocities in km/s for given mean anomalies.

Returns 3-D positions and velocities as SkyCoord objects, in “observer” reference frame. Uses kepler.Efn() to calculate eccentric anomalies using interpolation.

Parameters:

• Ms,eccs,semimajors,mreds – (float or array-like) Mean anomalies, eccentricities, semimajor axes [AU], reduced masses [Msun].
• obspos – (None, (x,y,z) tuple or SkyCoord object) Locations of observers for which to return coordinates. If None then populate randomly on sphere. If (x,y,z) or SkyCoord object provided, then use those.

Returns pos,vel:  

SkyCoord Objects representing the positions and velocities, the coordinates of which are Quantity objects that have units. Positions are in projected AU and velocities in km/s.

vespa.orbits.utils.orbitproject(x, y, inc, phi=0, psi=0)

Transform x,y planar coordinates into observer’s coordinate frame.

x,y are coordinates in z=0 plane (plane of the orbit)

observer is at (inc, phi) on celestial sphere (angles in radians); psi is orientation of final x-y axes about the (inc,phi) vector.

Returns x,y,z values in observer’s coordinate frame, where x,y are now plane-of-sky coordinates and z is along the line of sight.

Parameters:

• x,y – (float or array-like) Coordinates to transform.
• inc – (float or array-like) Polar angle(s) of observer (where inc=0 corresponds to north pole of original x-y plane). This angle is the same as standard “inclination.”
• phi – (float or array-like, optional) Azimuthal angle of observer around z -axis
• psi – (float or array-like, optional) Orientation of final observer coordinate frame (azimuthal around (inc,phi) vector.

Return x,y,z:

(ndarray) Coordinates in observers’ frames. x,y in “plane of sky” and z along line of sight.

vespa.orbits.utils.random_spherepos(n)

Returns SkyCoord object with n positions randomly oriented on the unit sphere.

Parameters:n – (int) Number of positions desired. Return c:astropy.coordinates.SkyCoord object with random positions