Describes a system of two bodies orbiting each other. More...

#include <BinarySystem.h>

Inheritance diagram for Evolve::BinarySystem:

Collaboration diagram for Evolve::BinarySystem:

Public Member Functions
	BinarySystem (DissipatingBody &body1, DissipatingBody &body2, const std::string &system_name="")
	Construct a binary system. More...

const std::string	get_name () const
	Returns the name of the system. More...

virtual int	configure (bool initialize, double age, double semimajor, double eccentricity, const double spin_angmom, const double inclination, const double *periapsis, Core::EvolModeType evolution_mode)
	Sets the current state of the system. More...

int	configure (bool initialize, double age, const double *parameters, Core::EvolModeType evolution_mode)

double	age () const
	Returns the present age of the system in Gyr. More...

const DissipatingBody &	primary () const
	Returns the primary body in the system (const). More...

const DissipatingBody &	secondary () const
	Returns the secondary body in the system (const). More...

unsigned	number_zones () const
	The total number of zones in both system bodies. More...

unsigned	number_locked_zones () const
	How many zones on either body are currently locked. More...

double	semimajor () const
	The current semimajor axis of the system. More...

double	eccentricity () const
	The current eccentricity of the system. More...

double	orbital_frequency (bool semimajor_deriv=false) const
	The current orbital frequency [Rad/day] (calculated from the semimajor axis). More...

Core::EvolModeType	fill_orbit (std::valarray< double > &orbit) const
	Fills an array with the parameters expected by differential_equations() and jacobian(), returning the evolution mode. More...

double	above_lock_fraction (unsigned locked_zone_index, Dissipation::QuantityEntry entry=Dissipation::NO_DERIV, unsigned deriv_zone_index=0, bool secondary_radius=false)
	The fraction of an infinitesimal timestep that a zone spends spinning faster than the lock it is in. More...

int	differential_equations (double age, const double parameters, Core::EvolModeType evolution_mode, double differential_equations)
	The differential equation and jacobian for the evolution of the system. More...

void	initialize_locks (double sync_precision)
	Identify and lock all zones within precision of a lock that can hold the lock at the current configuration. More...

void	check_for_lock (int orbital_freq_mult, int spin_freq_mult, unsigned short body_index, unsigned zone_index, short direction)
	Check if a spin-orbit lock can be held and updates the system as necessary to calculate subsequent evolution. More...

virtual double	minimum_separation (bool deriv=false) const
	Smallest semimajor axis at which the secondary can survive for the latest system configuration. More...

Core::EvolModeType	evolution_mode ()
	The evolution mode of last call to configure(). More...

virtual void	secondary_died ()
	Update the system to account for the death of the secondary. More...

virtual void	release_lock (unsigned locked_zone_index, short direction)
	Releases the lock to one of the locked zones. More...

virtual void	add_to_evolution ()
	Appends the state defined by last configure(), to the evolution. More...

virtual void	reset_evolution ()
	Resets the evolution of the system. More...

virtual void	rewind_evolution (unsigned nsteps)
	Discards the last steps from the evolution. More...

virtual CombinedStoppingCondition *	stopping_conditions ()
	Conditions detecting the next possible doscontinuity in the evolution. More...

virtual void	reached_critical_age (double age)
	Change the system as necessary at the given age. More...

virtual double	next_stop_age () const
	The next age when the evolution needs to be stopped for a system change. More...

const std::list< double > &	semimajor_evolution () const
	The tabulated evolution of the semimajor axis so far. More...

const std::list< double > &	semimajor_evolution_rate () const
	The tabulated evolution of the semimajor axis so far. More...

const std::list< double > &	eccentricity_evolution () const
	The tabulated evolution of the eccentricity so far. More...

const std::list< double > &	eccentricity_evolution_rate () const
	The tabulated evolution of the eccentricity so far. More...

virtual void	change_expansion_order (unsigned new_expansion_order)
	Change the tidal potential expansion order for all dissipative zones. More...

virtual unsigned	expansion_order () const

Private Types
typedef std::list< std::tuple< unsigned, short, double > >	lock_scenario_type

Private Member Functions
void	find_locked_zones ()
	Fills the __locked_zones list. More...

lock_scenario_type	find_synchronized_zones (double precision)
	Return a list of the zone indices that are spin-orbit synchronized with some tidal term (locked or unlocked). More...

void	set_lock_scenario (const lock_scenario_type &lock_scenario)
	Lock exactly the specified zones and configure the system. More...

void	unlock_all_zones (const std::vector< short > &unlock_directions, const std::vector< double > &original_angmom=std::vector< double >())
	Unlock all zones, restoring their original spins if known. More...

bool	test_synchronized_unlocked_zone (unsigned test_zone_ind)

void	describe_lock_scenario (std::ostream &os, const lock_scenario_type &lock_scenario, const std::vector< bool > passed, bool add_header=false)

bool	test_lock_scenario (const lock_scenario_type &lock_scenario, bool first_scenario)
	Return true iff all locks in the given scenario will be maintained and synchronized unlocked zones will evolve away from lock. More...

bool	explore_lock_scenarios (lock_scenario_type::const_iterator next_synchronized_zone, unsigned num_synchronized_zones, lock_scenario_type &lock_scenario, bool first_scenario=true)
	Iterate over all possible lock scenarios until a valid one is found. More...

int	locked_surface_differential_equations (double *evolution_rates) const
	Differential equations for the rotation of the zones of body 0 with the topmost zone rotating with a fixed frequency. More...

int	single_body_differential_equations (double *evolution_rates) const
	Differential equations for the rotation of the zones of body 0 if no other body is present. More...

double	semimajor_evolution (double orbit_power, double orbit_power_deriv=Core::NaN) const
	Returns the rate of evolution of the semimajor axis or one of its derivatives. More...

double	eccentricity_evolution (double orbit_power, double orbit_angmom_gain, double orbit_power_deriv=Core::NaN, double orbit_angmom_gain_deriv=Core::NaN, bool semimajor_deriv=true) const
	Returns the rate of evolution of the eccentricity or one of its derivatives. More...

void	above_lock_problem_deriv_correction (Dissipation::QuantityEntry entry, bool body1_deriv, Eigen::MatrixXd &matrix, Eigen::VectorXd &rhs) const
	Makes corrections to the matrix and RHS to accomodate the given derivative for the linear problem that defines the above fractions. More...

void	calculate_above_lock_fractions (Eigen::VectorXd &fractions, Dissipation::QuantityEntry entry=Dissipation::NO_DERIV, bool body1_deriv=true)
	Calculates the fraction of a timestep above spin-orbit lock for all locked zones. More...

Eigen::VectorXd	above_lock_fractions_deriv (Dissipation::QuantityEntry entry, DissipatingBody &body, unsigned zone_index)
	Calculates derivatives of the above lock fractions w.r.t. quantities of non-surface zones. More...

void	fill_above_lock_fractions_deriv ()
	Fills the __above_lock_fractinos_*_deriv members. More...

void	update_above_lock_fractions ()
	Solves for and sets the above lock fractions and their derivatives. More...

void	fill_orbit_torque_and_power ()
	Update the values of ::__orbit_power, ::__orbit_torque, and ::__orbit_angmom_gain. More...

int	binary_differential_equations (double *differential_equations) const
	The differential equations for a system with both bodies present. More...

template<typename VALUE_TYPE >
void	add_body_rate_deriv (const DissipatingBody &body, VALUE_TYPE(DissipatingBody::*func)(Dissipation::QuantityEntry, unsigned, const Eigen::VectorXd &) const, std::valarray< VALUE_TYPE > &orbit_rate_deriv, unsigned offset) const
	Adds the derivatives of a rate by which the orbit is changing due to tidal interactions with a single body to an array. More...

void	fill_orbit_power_deriv (std::valarray< double > &orbit_power_deriv) const
	Computes the derivatives w.r.t. the evolution quantities of the orbit energy gain. More...

void	fill_orbit_angmom_gain_deriv (std::valarray< double > &orbit_angmom_gain_deriv) const
	Computes the derivatives w.r.t. the evolution quantities of the orbit angular momentum gain. More...

void	fill_locked_surface_orbit (std::valarray< double > &orbit) const
	Implements fill_orbit() for LOCKED_SURFACE_SPIN evolution mode. More...

void	fill_binary_orbit (std::valarray< double > &orbit) const
	Implements fill_orbit() for BINARY evolution mode. More...

void	fill_single_orbit (std::valarray< double > &orbit) const
	Implements fill_orbit() for SINGLE evolution mode. More...

Private Attributes
std::string	__name
	The name of the binary system (e.g. "HAT-P-20") More...

std::list< double >	__semimajor_evolution
	The evolution of the semimajor axis recorded by add_to_evolution() so far. More...

std::list< double >	__eccentricity_evolution
	The evolution of the eccentricity recorded by add_to_evolution() so far. More...

std::list< double >	__semimajor_rate_evolution
	The rate at which the semimajor axis evolved at each. More...

std::list< double >	__eccentricity_rate_evolution
	The rate at which the eccentricity evolved at each. More...

double	__age
	The present age of the stellar system in Gyrs. More...

double	__semimajor
	The current semimajor axis. More...

double	__eccentricity
	The current eccentricity. More...

double	__orbital_energy
	The current orbital energy. More...

double	__orbital_angmom
	The current orbital angular momentum. More...

double	__orbit_power
	The rate at which the orbit gains energy due to tides. More...

double	__orbit_angmom_gain
	The rate at which the orbit gains angular momentum due to tides. More...

double	__semimajor_rate
	The current rate at which the semiamjor axis is changing. More...

double	__eccentricity_rate
	The current rate at which the eccentricity is changing. More...

Eigen::Vector3d	__orbit_torque
	The torque on the orbit in the coordinate system of the outermost zone of the first body. More...

Core::EvolModeType	__evolution_mode
	The evolution mode from the last call to configure();. More...

std::list< unsigned >	__locked_zones
	A list of indices of locked zones. More...

std::valarray< Eigen::VectorXd >	__above_lock_fractions
	The above lock fractinos for the locked zones and their derivatives. More...

std::valarray< Eigen::VectorXd >	__above_lock_fractions_inclination_deriv
	The derivatives of the above lock fractions w.r.t. the inclinations of the zones. More...

std::valarray< Eigen::VectorXd >	__above_lock_fractions_periapsis_deriv
	The derivatives of the above lock fractions w.r.t. the periapses of the zones. More...

std::valarray< Eigen::VectorXd >	__above_lock_fractions_inertia_deriv
	The derivatives of the above lock fractions w.r.t. the moments of inertia of the zones. More...

std::valarray< Eigen::VectorXd >	__above_lock_fractions_angmom_deriv
	The derivatives of the above lock fractions w.r.t. the angular momenta of the zones. More...

Eigen::VectorXd	__above_lock_fractions_body2_radius_deriv
	The derivative of the above lock fractions w.r.t. to the radius of the secondardy. More...

Eigen::ColPivHouseholderQR< Eigen::MatrixXd >	__above_lock_fractions_decomp
	The matrix that defines the problem to solve for __above_lock_fractions. More...

DissipatingBody &	__body1
	The first body in the system. More...

DissipatingBody &	__body2
	The second body in the system. More...

lock_scenario_type	__selected_lock_scenario
	The lock/unlock configuration selected by the last call to. More...

Detailed Description

Describes a system of two bodies orbiting each other.

The following variable are referred to throughout:

age: Gyr
a: semimajor axis in \(R_\odot\) (average distance between the bodies)
e: the eccentricity of the orbit
Eorb: the energy of the orbit (potential + kinetic) treating the two bodies as point masses in \(GM_\odot^2/R_\odot\).
L: angular momentum of the orbit treating the two bodies as point masses in \(M_\odot\cdot R_\odot^2 \cdot \mathrm{rad}/\mathrm{day}\)
\(\theta^b_i\): inclination of the i-th zone of the b-th body relative to the orbit in radians.
\(\omega^b_i\): argument of periapsis of the orbit for the i-th zone of the b-th body with a plane of reference perpendicular to that zone's spin.
\(S^b_i\): spin angular momentum of the i-th zone of the b-th body in \(M_\odot\cdot R_\odot^2 \cdot \mathrm{rad}/\mathrm{day}\).

The index of the outermost zone of a body is zero and increases inward.

All rates of change are per Gyr

Positive tidal power and tidal torque mean that energy is being removed from the orbit and deposited into the bodies.

Definition at line 57 of file BinarySystem.h.

Constructor & Destructor Documentation

◆ BinarySystem()

Evolve::BinarySystem::BinarySystem	(	DissipatingBody &	body1,
		DissipatingBody &	body2,
		const std::string &	system_name = `""`
	)

inline

Construct a binary system.

Parameters

body1	The first body in the system. Assumed to always be there, so for a star-planet system this should be the star.
body2	The second body in the system, initially may not be there and later may be engulfed by the first body.
system_name	The name of the system.

Definition at line 844 of file BinarySystem.h.

Member Function Documentation

◆ above_lock_fraction()

double Evolve::BinarySystem::above_lock_fraction	(	unsigned	locked_zone_index,
		Dissipation::QuantityEntry	entry = `Dissipation::NO_DERIV`,
		unsigned	deriv_zone_index = `0`,
		bool	secondary_radius = `false`
	)

The fraction of an infinitesimal timestep that a zone spends spinning faster than the lock it is in.

Parameters

locked_zone_index	The index within the list of locked zones of the zone we need.
entry	What derivative to return. Only non-zone specific quantities and, Dissipation::INCLINATION, Dissipation::PERIAPSIS, Dissipation::SPIN_ANGMOM and Dissipation::MOMENT_OF_INERTIA are allowed.
deriv_zone_index	The index of the zone whose quantity we want the derivative w.r.t. for zone specific quantities.
secondary_radius	If deriv==Dissipation::RADIUS this argument determines the body whose radius the derivative is w.r.t.

Definition at line 2482 of file BinarySystem.cpp.

◆ above_lock_fractions_deriv()

Eigen::VectorXd Evolve::BinarySystem::above_lock_fractions_deriv	(	Dissipation::QuantityEntry	entry,
		DissipatingBody &	body,
		unsigned	zone_index
	)

private

Calculates derivatives of the above lock fractions w.r.t. quantities of non-surface zones.

Parameters

entry	The derivative to calculate. Only INCLINATION, PERIAPSIS, MOMENT_OF_INERTIA and SPIN_ANGMOM derivatives are supported.
body	The body whose zone's inclination we want the derivative w.r.t.
zone_index	The zone whose inclination we are finding the derivative w.r.t.

Definition at line 1160 of file BinarySystem.cpp.

◆ above_lock_problem_deriv_correction()

void Evolve::BinarySystem::above_lock_problem_deriv_correction	(	Dissipation::QuantityEntry	entry,
		bool	body1_deriv,
		Eigen::MatrixXd &	matrix,
		Eigen::VectorXd &	rhs
	)		const

private

Makes corrections to the matrix and RHS to accomodate the given derivative for the linear problem that defines the above fractions.

Parameters

entry	The derivative being calculated
body1_deriv	For zone-specific quantities, are we differentiating w.r.t. a zone part of body1?
matrix	The matrix to update.
rhs	The RHS vector to update.

Definition at line 954 of file BinarySystem.cpp.

◆ add_body_rate_deriv()

template<typename VALUE_TYPE >

void Evolve::BinarySystem::add_body_rate_deriv	(	const DissipatingBody &	body,
		VALUE_TYPE(DissipatingBody::*)(Dissipation::QuantityEntry, unsigned, const Eigen::VectorXd &) const	func,
		std::valarray< VALUE_TYPE > &	orbit_rate_deriv,
		unsigned	offset
	)		const

private

Adds the derivatives of a rate by which the orbit is changing due to tidal interactions with a single body to an array.

With the appropriate arguments this can either add the rate of change of the orbital energy or the torque on the orbit due to the tides on one body to the given array.

Parameters

body	The body whose contribution we wish to add.
func	The quantity we are collecting. Should be either body.tidal_orbit_power or body.tidal_orbit_torque.
orbit_rate_deriv	The array to add to. The indices match the parameters being evolved.
offset	If body is __body1 this should be zero, if it is __body2, it should be the number of zones in __body1.

Definition at line 1454 of file BinarySystem.cpp.

◆ add_to_evolution()

void Evolve::BinarySystem::add_to_evolution ( )

virtual

Appends the state defined by last configure(), to the evolution.

Definition at line 2783 of file BinarySystem.cpp.

◆ age()

double Evolve::BinarySystem::age ( ) const

inline

Returns the present age of the system in Gyr.

Definition at line 914 of file BinarySystem.h.

◆ binary_differential_equations()

int Evolve::BinarySystem::binary_differential_equations ( double * differential_equations ) const

private

The differential equations for a system with both bodies present.

Also updates the current evolution rate private members if expansion_error is false.

Parameters

differential_equations On output is set to the rates of change of the evolution variables. See differintal_equations() for details.

Definition at line 1332 of file BinarySystem.cpp.

◆ calculate_above_lock_fractions()

void Evolve::BinarySystem::calculate_above_lock_fractions	(	Eigen::VectorXd &	fractions,
		Dissipation::QuantityEntry	entry = `Dissipation::NO_DERIV`,
		bool	body1_deriv = `true`
	)

private

Calculates the fraction of a timestep above spin-orbit lock for all locked zones.

The configure() method must already have been called.

Only locked zones get an entry. The locked zones of body1 are first from outside to inside, followed by the locked zones for body2.

Parameters

fractions	The vector to fill with the calculated fractions.
entry	The derivative of the above lock fractions to calculate. For zone-dependent quantities the derivatives are w.r.t. the surface zone quantity.
body1_deriv	Only used if deriv indicates a zone-dependent quantity. In that case, it specifies the body whose surface zone we are differentiating against.

Definition at line 1050 of file BinarySystem.cpp.

◆ change_expansion_order()

virtual void Evolve::BinarySystem::change_expansion_order ( unsigned new_expansion_order )

inlinevirtual

Change the tidal potential expansion order for all dissipative zones.

Parameters

new_expansion_order The new expansion order.

Definition at line 1157 of file BinarySystem.h.

◆ check_for_lock()

void Evolve::BinarySystem::check_for_lock	(	int	orbital_freq_mult,
		int	spin_freq_mult,
		unsigned short	body_index,
		unsigned	zone_index,
		short	direction
	)

Check if a spin-orbit lock can be held and updates the system as necessary to calculate subsequent evolution.

Parameters

orbital_freq_mult	The multiplier of the orbital frequency at the lock
spin_freq_mult	The multiplier of the spin frequency of the potentially locked zone at the lock.
body_index	The body whose zone is being locked.
zone_index	The zone being unlocked.
direction	The direction in which the lock will be left if it does not hold.

Definition at line 2599 of file BinarySystem.cpp.

◆ configure() [1/2]

int Evolve::BinarySystem::configure	(	bool	initialize,
		double	age,
		double	semimajor,
		double	eccentricity,
		const double *	spin_angmom,
		const double *	inclination,
		const double *	periapsis,
		Core::EvolModeType	evolution_mode
	)

virtual

Sets the current state of the system.

Parameters

initialize	Is this the first time configure() is invoked?
age	The age to set the system to.
semimajor	The semimajor axis of the orbit.
eccentricity	The eccentricity of the orbit.
spin_angmom	The spin angular momenta of the zones of the bodies (body 1 first, outermost zone to innermost, followed by body 2).
inclination	The inclinations of the zones of the bodies (same order as spin_angmom). The surface zone inclination must be omitted for single body systems.
periapsis	The arguments of periapsis of the zones of the bodies (same order as spin_angmom, but not including the surface zone of the first body).
evolution_mode	The evolution mode to assume.

Definition at line 2321 of file BinarySystem.cpp.

◆ configure() [2/2]

int Evolve::BinarySystem::configure	(	bool	initialize,
		double	age,
		const double *	parameters,
		Core::EvolModeType	evolution_mode
	)

Sets the current state of the system directly from the evolution variables.

Parameters

initialize	Is this the first time configure() is invoked?
age	The current age of the system.
parameters	The parameters being evolved. See differential_equations().
evolution_mode	The evolution mode to assume for the system.

Definition at line 2414 of file BinarySystem.cpp.

◆ describe_lock_scenario()

void Evolve::BinarySystem::describe_lock_scenario	(	std::ostream &	os,
		const lock_scenario_type &	lock_scenario,
		const std::vector< bool >	passed,
		bool	add_header = `false`
	)

private

Parameters

os	Thes straem to send the zone description to.
lock_scenario	The scenario to decsribe in the same format as returned by find_synchronized_zones().
passed	Flags indicating whether each of the tested zones passed the test.
add_header	Should a header be added?

Definition at line 302 of file BinarySystem.cpp.

◆ differential_equations()

int Evolve::BinarySystem::differential_equations	(	double	age,
		const double *	parameters,
		Core::EvolModeType	evolution_mode,
		double *	differential_equations
	)

The differential equation and jacobian for the evolution of the system.

Deliberate side effects:

Calls configure().
Updates instantaneous evolution rates if expansion_error is false.

Parameters

age	The current age of the system.
parameters	Contains the variables being evolved. The expected content depends on the values of evolution_mode and mhether any spin-orbit locks are held.

If evolution_mode is LOCKED_SURFACE_SPIN:

\(S^0_i,\ i=1\ldots\) - all zones' spin axes are assumed aligned

If evolution mode is SINGLE

\(theta^0_i,\ i=1\ldots\) ( \(\theta^0_0\equiv0\))
\(\omega^0_i,\ i=1\ldots\) ( \(\omega^0_0\equiv0\))
\(S^0_i,\ i=0,1,\ldots\)

The TABULATION evolution mode is not allowed.

If evolution mode is BINARY

a^6.5 if no zones are locked, a otherwise
e
\(\theta^0_i,\ i=0,\ldots\)
\(\theta^1_i,\ i=0,\ldots\)
\(\omega^0_i,\ i=1,\ldots\) ( \(\omega^0_0\equiv0\))
\(\omega^1_i,\ i=0,\ldots\)
\(S^0_i,\ i=0\ldots\) with zones in spin-orbit lock omitted

\(S^1_i,\ i=0\ldots\) with zones in spin-orbit lock omitted

Parameters

evolution_mode	The evolution mode to assume for the system.
differential_equations	On outputs gets filled with the rates at which the entries in parameters evolve. It is assumed that sufficient space has been allocated to hold the results.

Definition at line 2515 of file BinarySystem.cpp.

◆ eccentricity()

double Evolve::BinarySystem::eccentricity ( ) const

inline

The current eccentricity of the system.

Definition at line 936 of file BinarySystem.h.

◆ eccentricity_evolution() [1/2]

double Evolve::BinarySystem::eccentricity_evolution	(	double	orbit_power,
		double	orbit_angmom_gain,
		double	orbit_power_deriv = `Core::NaN`,
		double	orbit_angmom_gain_deriv = `Core::NaN`,
		bool	semimajor_deriv = `true`
	)		const

private

Returns the rate of evolution of the eccentricity or one of its derivatives.

The orbit and age of the system must already be set by calling configure().

Supports differentiation with repesct to the semimajor axis and eccentricity. If derivatives with respect to other quantities are required, simply provide the derivative of the tidal power and torque with respect to the quantity as the first and second arguments.

Parameters

orbit_power	See semimajor_evolution()
orbit_angmom_gain	The rate at which the orbit gains angular momentum (total for all zones of all bodies) in \(M_\odot R_\odot^2 \mathrm{day}^{-2}\mathrm{Gyr}^{-1}\)
orbit_power_deriv	If this is not NaN, the derivative of the eccentricity evolution rate w.r.t. either the semimajor axis or the case, this value must be the derivative of orbit_power w.r.t. the same this as the desired derivative.
orbit_angmom_gain_deriv	If orbit_power_deriv is not NaN, this must be set to the derivative of orbit_torque with respect to the same variable as orbit_power_deriv.
semimajor_deriv	If true the derivative calculated is assumed to be w.r.t. the semimajor axis.

Definition at line 899 of file BinarySystem.cpp.

◆ eccentricity_evolution() [2/2]

const std::list<double>& Evolve::BinarySystem::eccentricity_evolution ( ) const

inline

The tabulated evolution of the eccentricity so far.

Definition at line 1149 of file BinarySystem.h.

◆ eccentricity_evolution_rate()

const std::list<double>& Evolve::BinarySystem::eccentricity_evolution_rate ( ) const

inline

The tabulated evolution of the eccentricity so far.

Definition at line 1153 of file BinarySystem.h.

◆ evolution_mode()

Core::EvolModeType Evolve::BinarySystem::evolution_mode ( )

inline

The evolution mode of last call to configure().

Definition at line 1093 of file BinarySystem.h.

◆ expansion_order()

unsigned Evolve::BinarySystem::expansion_order ( ) const

virtual

To what order should eccentricity expansion be performed for the given value of the eccentricity.

Definition at line 2838 of file BinarySystem.cpp.

◆ explore_lock_scenarios()

bool Evolve::BinarySystem::explore_lock_scenarios	(	lock_scenario_type::const_iterator	next_synchronized_zone,
		unsigned	num_synchronized_zones,
		lock_scenario_type &	lock_scenario,
		bool	first_scenario = `true`
	)

private

Iterate over all possible lock scenarios until a valid one is found.

Return true iff

Parameters

next_synchronized_zone	Iterator within the return value of find_synchronized_zones() pointing to the first zone not included in lock_scenario.
num_synchronized_zones	The total number of zones for which a scenario must be defined.
lock_scenario	Partially filled lock scenario to test.Is this the first scenario being explored

Definition at line 442 of file BinarySystem.cpp.

◆ fill_above_lock_fractions_deriv()

void Evolve::BinarySystem::fill_above_lock_fractions_deriv ( )

private

Fills the __above_lock_fractinos_*_deriv members.

Definition at line 1239 of file BinarySystem.cpp.

◆ fill_binary_orbit()

void Evolve::BinarySystem::fill_binary_orbit ( std::valarray< double > & orbit ) const

private

Implements fill_orbit() for BINARY evolution mode.

Definition at line 2264 of file BinarySystem.cpp.

◆ fill_locked_surface_orbit()

void Evolve::BinarySystem::fill_locked_surface_orbit ( std::valarray< double > & orbit ) const

private

Implements fill_orbit() for LOCKED_SURFACE_SPIN evolution mode.

Definition at line 2248 of file BinarySystem.cpp.

◆ fill_orbit()

Core::EvolModeType Evolve::BinarySystem::fill_orbit ( std::valarray< double > & orbit ) const

Fills an array with the parameters expected by differential_equations() and jacobian(), returning the evolution mode.

The system must be appropriately configure() -ed already.

Parameters

orbit The orbit to fill (resized as necessary).

Definition at line 2471 of file BinarySystem.cpp.

◆ fill_orbit_angmom_gain_deriv()

void Evolve::BinarySystem::fill_orbit_angmom_gain_deriv ( std::valarray< double > & orbit_angmom_gain_deriv ) const

private

Computes the derivatives w.r.t. the evolution quantities of the orbit angular momentum gain.

Parameters

orbit_angmom_gain_deriv Location to fill.

Definition at line 1529 of file BinarySystem.cpp.

◆ fill_orbit_power_deriv()

void Evolve::BinarySystem::fill_orbit_power_deriv ( std::valarray< double > & orbit_power_deriv ) const

private

Computes the derivatives w.r.t. the evolution quantities of the orbit energy gain.

Parameters

orbit_power_deriv Location to fill.

Definition at line 1514 of file BinarySystem.cpp.

◆ fill_orbit_torque_and_power()

void Evolve::BinarySystem::fill_orbit_torque_and_power ( )

private

Update the values of ::__orbit_power, ::__orbit_torque, and ::__orbit_angmom_gain.

Called as part of ::configure().

Definition at line 1309 of file BinarySystem.cpp.

◆ fill_single_orbit()

void Evolve::BinarySystem::fill_single_orbit ( std::valarray< double > & orbit ) const

private

Implements fill_orbit() for SINGLE evolution mode.

Definition at line 2295 of file BinarySystem.cpp.

◆ find_locked_zones()

void Evolve::BinarySystem::find_locked_zones ( )

private

Fills the __locked_zones list.

Definition at line 13 of file BinarySystem.cpp.

◆ find_synchronized_zones()

BinarySystem::lock_scenario_type Evolve::BinarySystem::find_synchronized_zones ( double precision )

private

Return a list of the zone indices that are spin-orbit synchronized with some tidal term (locked or unlocked).

The monitored locks of synchronized zones are swapped as necessary to ensure the first lock being monitored by the zone is the one that is (close to) synchronized.

The entries in each return value give:

0: the index of the zone (__body1 followed by __body2)

1: The current direction of the synchronized lock for that zone.

2: The current angular momentum of the zone

Parameters

precision A spin-orbit term is considered synchronized if its tidal frequnecy is within this fraction of the orbital frequency.

Definition at line 31 of file BinarySystem.cpp.

◆ get_name()

const std::string Evolve::BinarySystem::get_name ( ) const

inline

Returns the name of the system.

Definition at line 863 of file BinarySystem.h.

◆ initialize_locks()

void Evolve::BinarySystem::initialize_locks ( double sync_precision )

Identify and lock all zones within precision of a lock that can hold the lock at the current configuration.

Parameters

sync_precision A tidal term is considered to have zero frequency (candidate to lock) if its absolute frequency is less than sync_precision times the orbital frequency.

Definition at line 2574 of file BinarySystem.cpp.

◆ locked_surface_differential_equations()

int Evolve::BinarySystem::locked_surface_differential_equations ( double * evolution_rates ) const

private

Differential equations for the rotation of the zones of body 0 with the topmost zone rotating with a fixed frequency.

The age of the system must already be set appropriately by configure().

Parameters

evolution_rates On output is set to the rates of change of \(S^0_i\).

Definition at line 518 of file BinarySystem.cpp.

◆ minimum_separation()

double Evolve::BinarySystem::minimum_separation ( bool deriv = false ) const

virtual

Smallest semimajor axis at which the secondary can survive for the latest system configuration.

By default returns the larger of:

primary radius.
2.44*(secondary radius)*((primary mass)/(secondary mass))^(1/3)

Parameters

deriv If true the rate of change (per Gyr) is returned.

Definition at line 2678 of file BinarySystem.cpp.

◆ next_stop_age()

double Evolve::BinarySystem::next_stop_age ( ) const

virtual

The next age when the evolution needs to be stopped for a system change.

Reimplemented in Evolve::DiskBinarySystem.

Definition at line 2832 of file BinarySystem.cpp.

◆ number_locked_zones()

unsigned Evolve::BinarySystem::number_locked_zones ( ) const

inline

How many zones on either body are currently locked.

Definition at line 929 of file BinarySystem.h.

◆ number_zones()

unsigned Evolve::BinarySystem::number_zones ( ) const

inline

The total number of zones in both system bodies.

Definition at line 923 of file BinarySystem.h.

◆ orbital_frequency()

double Evolve::BinarySystem::orbital_frequency ( bool semimajor_deriv = false ) const

inline

The current orbital frequency [Rad/day] (calculated from the semimajor axis).

Definition at line 940 of file BinarySystem.h.

◆ primary()

const DissipatingBody& Evolve::BinarySystem::primary ( ) const

inline

Returns the primary body in the system (const).

Definition at line 917 of file BinarySystem.h.

◆ reached_critical_age()

void Evolve::BinarySystem::reached_critical_age ( double age )

virtual

Change the system as necessary at the given age.

Handles things like the disk dissipating, the planet forming and interpolation discontinuities.

Reimplemented in Evolve::DiskBinarySystem.

Definition at line 2826 of file BinarySystem.cpp.

◆ release_lock()

void Evolve::BinarySystem::release_lock	(	unsigned	locked_zone_index,
		short	direction
	)

virtual

Releases the lock to one of the locked zones.

Parameters

locked_zone_index	The index within the list of locked zones of the zone to unlock.
direction	The direction in which the zone's spin will evolve in the future relative to the lock.

Definition at line 2751 of file BinarySystem.cpp.

◆ reset_evolution()

void Evolve::BinarySystem::reset_evolution ( )

virtual

Resets the evolution of the system.

Definition at line 2793 of file BinarySystem.cpp.

◆ rewind_evolution()

void Evolve::BinarySystem::rewind_evolution ( unsigned nsteps )

virtual

Discards the last steps from the evolution.

Parameters

nsteps How many steps of evolution to discard.

Definition at line 2803 of file BinarySystem.cpp.

◆ secondary()

const DissipatingBody& Evolve::BinarySystem::secondary ( ) const

inline

Returns the secondary body in the system (const).

Definition at line 920 of file BinarySystem.h.

◆ secondary_died()

void Evolve::BinarySystem::secondary_died ( )

virtual

Update the system to account for the death of the secondary.

Adds the entire orbital angular momentum to the surface zone of the primary and enters single body evolution mode.

Definition at line 2701 of file BinarySystem.cpp.

◆ semimajor()

double Evolve::BinarySystem::semimajor ( ) const

inline

The current semimajor axis of the system.

Definition at line 933 of file BinarySystem.h.

◆ semimajor_evolution() [1/2]

double Evolve::BinarySystem::semimajor_evolution	(	double	orbit_power,
		double	orbit_power_deriv = `Core::NaN`
	)		const

private

Returns the rate of evolution of the semimajor axis or one of its derivatives.

The age and the orbit of the system must already be set by calling configure().

Supports differentiation with repesct to the semimajor axis. If derivatives with respect to other quantities are required, simply provide the derivative of the tidal power with respect to the quantity as the first argument.

Parameters

orbit_power	The rate at which the orbit gains energy (total for all zones of all bodies) in \(M_\odot R_\odot^2 \mathrm{day}^{-2}\mathrm{Gyr}^{-1}\)
orbit_power_deriv	If not NaN, the derivative with respect to the semimajoir axis is returned, assuming that this is the derivative of orbit_power with respect to the semimajor axis.

Definition at line 876 of file BinarySystem.cpp.

◆ semimajor_evolution() [2/2]

const std::list<double>& Evolve::BinarySystem::semimajor_evolution ( ) const

inline

The tabulated evolution of the semimajor axis so far.

Definition at line 1141 of file BinarySystem.h.

◆ semimajor_evolution_rate()

const std::list<double>& Evolve::BinarySystem::semimajor_evolution_rate ( ) const

inline

The tabulated evolution of the semimajor axis so far.

Definition at line 1145 of file BinarySystem.h.

◆ set_lock_scenario()

void Evolve::BinarySystem::set_lock_scenario ( const lock_scenario_type & lock_scenario )

private

Lock exactly the specified zones and configure the system.

Also preserves the unlocked angular momenta to allow recovering the unlocked system exactly.

Parameters

lock_scenario The zones to lock/unlock in the same format as the return value of find_synchronizedzones(). Angular momentum for locked zones is ignored.

Definition at line 87 of file BinarySystem.cpp.

◆ single_body_differential_equations()

int Evolve::BinarySystem::single_body_differential_equations ( double * evolution_rates ) const

private

Differential equations for the rotation of the zones of body 0 if no other body is present.

configure() must already have been called.

Parameters

evolution_rates On outputs is set to the rate of change of the orbital parameters.

Definition at line 647 of file BinarySystem.cpp.

◆ stopping_conditions()

CombinedStoppingCondition * Evolve::BinarySystem::stopping_conditions ( )

virtual

Conditions detecting the next possible doscontinuity in the evolution.

Must be deleted when no longer necessary.

Definition at line 2815 of file BinarySystem.cpp.

◆ test_lock_scenario()

bool Evolve::BinarySystem::test_lock_scenario	(	const lock_scenario_type &	lock_scenario,
		bool	first_scenario
	)

private

Return true iff all locks in the given scenario will be maintained and synchronized unlocked zones will evolve away from lock.

Parameters

lock_scenario The scenario to test in the same format as returned by find_synchronized_zones(). Is this the first scenario being tested?

Definition at line 362 of file BinarySystem.cpp.

◆ test_synchronized_unlocked_zone()

bool Evolve::BinarySystem::test_synchronized_unlocked_zone ( unsigned test_zone_ind )

private

Check if a zone with a synchronized tidal term will evolve away from potential lock

Parameters

test_zone_ind The index of the zone to test in the total list of zones in the system (i.e. all zones of __body1 followed by __body2).

Definition at line 255 of file BinarySystem.cpp.

◆ unlock_all_zones()

void Evolve::BinarySystem::unlock_all_zones	(	const std::vector< short > &	unlock_directions,
		const std::vector< double > &	original_angmom = `std::vector<double>()`
	)

private

Unlock all zones, restoring their original spins if known.

Parameters

unlock_directions	The directions in which to unlock all the zones.
original_angmom	The original angular momenta to restore to the currently locked zones. Usually filled by prepare_lock_check(). If not specified, zones are unlocked with angular momenta placing them exactly at their current lock frequency.

Definition at line 210 of file BinarySystem.cpp.

◆ update_above_lock_fractions()

void Evolve::BinarySystem::update_above_lock_fractions ( )

private

Solves for and sets the above lock fractions and their derivatives.

The system must already be configure() -ed in in BINARY evolution mode.

Definition at line 1281 of file BinarySystem.cpp.

Member Data Documentation

◆ __above_lock_fractions

std::valarray<Eigen::VectorXd> Evolve::BinarySystem::__above_lock_fractions

private

The above lock fractinos for the locked zones and their derivatives.

For zone-dependent quantities, the derivatives are w.r.t. to the surface zone of __body1.

Definition at line 125 of file BinarySystem.h.

◆ __above_lock_fractions_angmom_deriv

std::valarray<Eigen::VectorXd> Evolve::BinarySystem::__above_lock_fractions_angmom_deriv

private

The derivatives of the above lock fractions w.r.t. the angular momenta of the zones.

Definition at line 125 of file BinarySystem.h.

◆ __above_lock_fractions_body2_radius_deriv

Eigen::VectorXd Evolve::BinarySystem::__above_lock_fractions_body2_radius_deriv

private

The derivative of the above lock fractions w.r.t. to the radius of the secondardy.

The derivative w.r.t. to the radius of the primary is already available as __above_lock_fractions[Dissipation::RADIUS].

Definition at line 148 of file BinarySystem.h.

◆ __above_lock_fractions_decomp

Eigen::ColPivHouseholderQR<Eigen::MatrixXd> Evolve::BinarySystem::__above_lock_fractions_decomp

private

The matrix that defines the problem to solve for __above_lock_fractions.

Useful when calculating derivatives.

Definition at line 155 of file BinarySystem.h.

◆ __above_lock_fractions_inclination_deriv

std::valarray<Eigen::VectorXd> Evolve::BinarySystem::__above_lock_fractions_inclination_deriv

private

The derivatives of the above lock fractions w.r.t. the inclinations of the zones.

Definition at line 125 of file BinarySystem.h.

◆ __above_lock_fractions_inertia_deriv

std::valarray<Eigen::VectorXd> Evolve::BinarySystem::__above_lock_fractions_inertia_deriv

private

The derivatives of the above lock fractions w.r.t. the moments of inertia of the zones.

Definition at line 125 of file BinarySystem.h.

◆ __above_lock_fractions_periapsis_deriv

std::valarray<Eigen::VectorXd> Evolve::BinarySystem::__above_lock_fractions_periapsis_deriv

private

The derivatives of the above lock fractions w.r.t. the periapses of the zones.

Definition at line 125 of file BinarySystem.h.

◆ __age

double Evolve::BinarySystem::__age

private

The present age of the stellar system in Gyrs.

Definition at line 81 of file BinarySystem.h.

◆ __body1

DissipatingBody& Evolve::BinarySystem::__body1

private

The first body in the system.

This is the body that is allowed to exist both before and after the second body does. It is also the body that should support surface locks.

Definition at line 163 of file BinarySystem.h.

◆ __body2

DissipatingBody & Evolve::BinarySystem::__body2

private

The second body in the system.

This body is never allowed to exist alone in the system or to have its surface rotation locked.

Definition at line 163 of file BinarySystem.h.

◆ __eccentricity

double Evolve::BinarySystem::__eccentricity

private

The current eccentricity.

Definition at line 81 of file BinarySystem.h.

◆ __eccentricity_evolution

std::list<double> Evolve::BinarySystem::__eccentricity_evolution

private

The evolution of the eccentricity recorded by add_to_evolution() so far.

Definition at line 65 of file BinarySystem.h.

◆ __eccentricity_rate

double Evolve::BinarySystem::__eccentricity_rate

mutableprivate

The current rate at which the eccentricity is changing.

Definition at line 105 of file BinarySystem.h.

◆ __eccentricity_rate_evolution

std::list<double> Evolve::BinarySystem::__eccentricity_rate_evolution

private

The rate at which the eccentricity evolved at each.

Definition at line 65 of file BinarySystem.h.

◆ __evolution_mode

Core::EvolModeType Evolve::BinarySystem::__evolution_mode

private

The evolution mode from the last call to configure();.

Definition at line 115 of file BinarySystem.h.

◆ __locked_zones

std::list<unsigned> Evolve::BinarySystem::__locked_zones

private

A list of indices of locked zones.

Definition at line 118 of file BinarySystem.h.

◆ __name

std::string Evolve::BinarySystem::__name

private

The name of the binary system (e.g. "HAT-P-20")

Definition at line 60 of file BinarySystem.h.

◆ __orbit_angmom_gain

double Evolve::BinarySystem::__orbit_angmom_gain

private

The rate at which the orbit gains angular momentum due to tides.

Definition at line 81 of file BinarySystem.h.

◆ __orbit_power

double Evolve::BinarySystem::__orbit_power

private

The rate at which the orbit gains energy due to tides.

Definition at line 81 of file BinarySystem.h.

◆ __orbit_torque

Eigen::Vector3d Evolve::BinarySystem::__orbit_torque

private

The torque on the orbit in the coordinate system of the outermost zone of the first body.

Definition at line 112 of file BinarySystem.h.

◆ __orbital_angmom

double Evolve::BinarySystem::__orbital_angmom

private

The current orbital angular momentum.

Definition at line 81 of file BinarySystem.h.

◆ __orbital_energy

double Evolve::BinarySystem::__orbital_energy

private

The current orbital energy.

Definition at line 81 of file BinarySystem.h.

◆ __selected_lock_scenario

lock_scenario_type Evolve::BinarySystem::__selected_lock_scenario

private

The lock/unlock configuration selected by the last call to.

Definition at line 178 of file BinarySystem.h.

◆ __semimajor

double Evolve::BinarySystem::__semimajor

private

The current semimajor axis.

Definition at line 81 of file BinarySystem.h.

◆ __semimajor_evolution

std::list<double> Evolve::BinarySystem::__semimajor_evolution

private

The evolution of the semimajor axis recorded by add_to_evolution() so far.

Definition at line 65 of file BinarySystem.h.

◆ __semimajor_rate

double Evolve::BinarySystem::__semimajor_rate

mutableprivate

The current rate at which the semiamjor axis is changing.

Definition at line 105 of file BinarySystem.h.

◆ __semimajor_rate_evolution

std::list<double> Evolve::BinarySystem::__semimajor_rate_evolution

private

The rate at which the semimajor axis evolved at each.

Definition at line 65 of file BinarySystem.h.

The documentation for this class was generated from the following files:

/home/kpenev/projects/git/poet/poet_src/Evolve/BinarySystem.h
/home/kpenev/projects/git/poet/poet_src/Evolve/BinarySystem.cpp

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BinarySystem()

Member Function Documentation

◆ above_lock_fraction()

◆ above_lock_fractions_deriv()

◆ above_lock_problem_deriv_correction()

◆ add_body_rate_deriv()

◆ add_to_evolution()

◆ age()

◆ binary_differential_equations()

◆ calculate_above_lock_fractions()

◆ change_expansion_order()

◆ check_for_lock()

◆ configure() [1/2]

◆ configure() [2/2]

◆ describe_lock_scenario()

◆ differential_equations()

◆ eccentricity()

◆ eccentricity_evolution() [1/2]

◆ eccentricity_evolution() [2/2]

◆ eccentricity_evolution_rate()

◆ evolution_mode()

◆ expansion_order()

◆ explore_lock_scenarios()

◆ fill_above_lock_fractions_deriv()

◆ fill_binary_orbit()

◆ fill_locked_surface_orbit()

◆ fill_orbit()

◆ fill_orbit_angmom_gain_deriv()

◆ fill_orbit_power_deriv()

◆ fill_orbit_torque_and_power()

◆ fill_single_orbit()

◆ find_locked_zones()

◆ find_synchronized_zones()

◆ get_name()

◆ initialize_locks()

◆ locked_surface_differential_equations()

◆ minimum_separation()

◆ next_stop_age()

◆ number_locked_zones()

◆ number_zones()

◆ orbital_frequency()

◆ primary()

◆ reached_critical_age()

◆ release_lock()

◆ reset_evolution()

◆ rewind_evolution()

◆ secondary()

◆ secondary_died()

◆ semimajor()

◆ semimajor_evolution() [1/2]

◆ semimajor_evolution() [2/2]

◆ semimajor_evolution_rate()

◆ set_lock_scenario()

◆ single_body_differential_equations()

◆ stopping_conditions()

◆ test_lock_scenario()

◆ test_synchronized_unlocked_zone()

◆ unlock_all_zones()

◆ update_above_lock_fractions()

Member Data Documentation

◆ __above_lock_fractions

◆ __above_lock_fractions_angmom_deriv

◆ __above_lock_fractions_body2_radius_deriv

◆ __above_lock_fractions_decomp

◆ __above_lock_fractions_inclination_deriv

◆ __above_lock_fractions_inertia_deriv

◆ __above_lock_fractions_periapsis_deriv

◆ __age

◆ __body1

◆ __body2

◆ __eccentricity

◆ __eccentricity_evolution

◆ __eccentricity_rate

◆ __eccentricity_rate_evolution