API Reference

Estimate initial orbital parameters.

SimulationSupport.EccentricityControl.InitialOrbitalParameters.initial_orbital_parameters(target_params, separation=None, orbital_angular_velocity=None, radial_expansion_velocity=None, method='PN', gpr_checkpoints=None)[source]

Estimate initial orbital parameters from PN or GPR.

Estimates initial orbital parameters from a Post-Newtonian (PN) approximation, or from a Gaussian Process Regression (GPR) correction to the PN approximation.

Given the target eccentricity and one other orbital parameter, this routine estimates the initial separation D_0, orbital angular velocity Omega_0, and radial expansion velocity adot_0 for a binary system. The resulting parameters can be fed into an eccentricity control loop to refine the starting parameters.

Parameters:

  • target_params (dict) –

    Simulation parameters that describe the binary. The dictionary must include the following keys:

    • "MassRatio": Mass ratio \(q = M_A / M_B \ge 1\).

    • "DimensionlessSpinA": Dimensionless spin vector of the larger black hole (length 3).

    • "DimensionlessSpinB": Dimensionless spin vector of the smaller black hole (length 3).

    • "Eccentricity": Target orbital eccentricity. Provide this value together with exactly one of the orbital parameters below.

    Optional keys:

    • "MeanAnomalyFraction": Mean anomaly divided by \(2\pi\) (between 0 and 1). Required for nonzero eccentricity.

    • "NumOrbits": Desired number of inspiral orbits until merger.

    • "TimeToMerger": Desired time to merger.

  • separation (float, optional) – Coordinate separation D_0 of the black holes.

  • orbital_angular_velocity (float, optional) – Orbital angular velocity Omega_0.

  • radial_expansion_velocity (float, optional) – Radial expansion velocity adot_0.

  • method (str, optional) – Either PN to compute parameters from the PN approximation, or GPR to apply a learned correction from a trained GPR model to the PN approximation

  • gpr_checkpoints (dict, optional) – Required when method = GPR. Maps the quantities to correct to the path of their trained GPR checkpoint file produced by save_gpr_checkpoint. Recognized keys are Omega0 and Adot0. Any quantity without an entry is left at its PN value and no correction is applied. D_0 is currently never corrected and is always returned at its PN value. Each checkpoint is checked against the quantity it is supplied for, so passing a checkpoint trained for a different quantity raises a ValueError instead of silently producing a wrong correction.

Returns:

A tuple (D_0, Omega_0, adot_0) with the initial separation, orbital angular velocity, and radial expansion velocity.

Return type:

tuple[float, float, float]

Estimate eccentricity and updated orbital parameters from trajectories.

SimulationSupport.EccentricityControl.EccentricityControlParams.eccentricity_control_params(trajectory_a, trajectory_b, separation, orbital_angular_velocity, radial_expansion_velocity, mass_a, mass_b, spin_a=None, spin_b=None, tmin=None, tmax=None, target_eccentricity=0.0, plot_output_dir=None)[source]

Get new orbital parameters for a binary system to control eccentricity.

The eccentricity is estimated from the trajectories of the binary objects and updates to the orbital parameters are suggested to drive the orbit to the target eccentricity, using SpEC’s OmegaDotEccRemoval.py. Currently supports only circular target orbits (target eccentricity = 0).

Parameters:

  • trajectory_a (numpy.ndarray) – Trajectory of the first object, with shape (num_times, 4). The first column is the time, the remaining three columns are the coordinates.

  • trajectory_b (numpy.ndarray) – Trajectory of the second object, in the same format as trajectory_a.

  • separation (float) – Initial coordinate separation D_0 of the two objects, i.e. the initial data parameter that is being controlled.

  • orbital_angular_velocity (float) – Initial orbital angular velocity Omega_0.

  • radial_expansion_velocity (float) – Initial radial expansion velocity adot_0.

  • mass_a (float) – Christodoulou mass of the first object at the reference time.

  • mass_b (float) – Christodoulou mass of the second object at the reference time.

  • spin_a (numpy.ndarray, optional) – Dimensionful spin of the first object, with shape (num_times, 4). The first column is the time, the remaining three columns are the components of the spin vector. If either spin is unspecified, spin effects are ignored in the fits.

  • spin_b (numpy.ndarray, optional) – Dimensionful spin of the second object, in the same format as spin_a.

  • tmin (float, optional) – The lower time bound for the eccentricity estimate. Used to remove initial junk and transients in the data. If unspecified, uses SpEC’s OmegaDotEccRemoval.FindTmin to estimate it.

  • tmax (float, optional) – The upper time bound for the eccentricity estimate. A reasonable value would include 2-3 orbits. Default is 500 + 5 * pi / Omega_0.

  • target_eccentricity (float, optional) – Eccentricity that the updated orbital parameters should achieve. Currently only 0 (circular orbit) is supported.

  • plot_output_dir (str or pathlib.Path, optional) – Output directory for plots.

Returns:

Dictionary with the keys listed in EccentricityParams.

Return type:

dict