Planetary Orbital Evolution due to Tides
Orbital evolution of two objects experiencing tides
Evolve::OrbitSolver Class Reference

Solves the system of ODEs describing the evolution of a single planet around a single star. More...

#include <OrbitSolver.h>

+ Collaboration diagram for Evolve::OrbitSolver:

Public Member Functions

 OrbitSolver (double max_age, double required_precision, bool print_progress=false)
 Prepare to solve for the orbital evolution. More...
 
void operator() (BinarySystem &system, double max_step=Core::Inf, const std::list< double > &required_ages=std::list< double >(), double max_runtime=0)
 Actually solves the given differential equation with the given boundary conditions. More...
 
const std::list< double > & evolution_ages () const
 The ages at which evolution has been tabulated so far. More...
 
const std::list< Core::EvolModeType > & mode_evolution () const
 The tabulated evolution modes so far. More...
 
 ~OrbitSolver ()
 Clean up. More...
 

Private Member Functions

void output_history_and_discarded (std::ostream &os)
 Generates a nicely formatted table of the contents of the discarded and history stopping condition information. More...
 
void clear_discarded ()
 Removes all stored discarded stop condition information. More...
 
void insert_discarded (double age, const std::valarray< double > &current_stop_cond, const std::valarray< double > &current_stop_deriv)
 Adds an entry in the discarded ages, stop conditions and derivatives. More...
 
void add_to_evolution (double age, Core::EvolModeType evolution_mode, BinarySystem &system)
 Adds the last step to the evolution. More...
 
double go_back (double max_age, BinarySystem &system, std::valarray< double > &orbit)
 Rewinds the evlution to the last step before the given age and returns the age of that step. More...
 
void clear_history ()
 Clears the current stopping condition history. More...
 
StopHistoryInterval select_stop_condition_interval (bool crossing, size_t cond_ind, size_t max_points) const
 Selects a history interval for interpolating to a reason to stop the evolution. More...
 
ExtremumInformation extremum_from_history_no_deriv (size_t condition_index) const
 Estimates the value and age of an extremum of a stopping condition for which no derivative information is available. More...
 
ExtremumInformation extremum_from_history (size_t condition_index) const
 Estimates the value and age of an extremum of a stopping condition for which derivative information is available. More...
 
double crossing_from_history_no_deriv (size_t condition_index) const
 Estimates the age at which a stopping condition with no derivative information crossed zero. More...
 
double crossing_from_history (size_t condition_index) const
 Estimates the age at which a stopping condition with derivative information crossed zero. More...
 
void initialize_skip_history (const StoppingCondition &stop_cond, StoppingConditionType stop_reason)
 Initializes the skip_history_zerocrossing and skip_history_extremum arrays appropriately after a mode change. More...
 
bool at_exact_condition (double previous_age, const StopInformation &stop_info)
 Is the condition causing a stop match to within the required precision? More...
 
bool acceptable_step (double current_age, double previous_age, const StopInformation &stop_info)
 Updates the skip_history_zerocrossing and skip_history_extremum arrays appropriately after an acceptable step. More...
 
int check_expansion_error (const std::valarray< double > &derivatives, const std::valarray< double > &expansion_errors)
 Return -1 if the expansion error is too small (e-order can safely be decreased, 0 if it is within range, 1 if it is too big. More...
 
StopInformation update_stop_condition_history (double age, const std::valarray< double > &orbit, const std::valarray< double > &derivatives, const std::valarray< double > &expansion_errors, Core::EvolModeType evolution_mode, StoppingConditionType stop_reason=NO_STOP, bool ignore_e_order_decrease=false)
 Updates stop_cond_history and stop_deriv_history after a GSL step, returning if/where the evolution needs to stop. More...
 
void reject_step (double &age, StopInformation &stop, BinarySystem &system, std::valarray< double > &orbit, double &max_next_t, double &step_size, std::string reason)
 Handle the situation when the last step has to be rejected. More...
 
StopInformation evolve_until (BinarySystem &system, double &max_age, std::valarray< double > &orbit, StoppingConditionType &stop_reason, double max_step, Core::EvolModeType evolution_mode)
 Evolves a system until either some age cut-off is reached or some stopping condition crosses zero. More...
 
CombinedStoppingConditionget_stopping_condition (BinarySystem &system)
 Returns the stopping conditions which end the given evolution mode and update __stop_info. More...
 
double stopping_age (double age, const BinarySystem &system, const std::list< double > &required_ages)
 The age at which the evolution should stop next if no other stopping condition occurs. More...
 
void reached_stopping_condition (double stop_age, StoppingConditionType stop_reason)
 Handle a stop in the evolution due to at least one condition reaching a critical value. More...
 
void adjust_eccentricity_order (BinarySystem &system, const std::valarray< double > &orbit, Core::EvolModeType evolution_mode, bool must_increase=false)
 Increase/decrease the eccentricity expansion order until error is acceptable and return the new order. More...
 
void reset (BinarySystem &system)
 Clears any previously calculated evolution. More...
 

Private Attributes

double __end_age
 The last age for which evolution is required. More...
 
double __precision
 The precision required of the solution. More...
 
double __e_order_downgrade_threshold
 If the fractional error due to truncating the eccentricity series falls below this value times the maximum acceptable error, the eccentricity order is downgraded. More...
 
double __last_e_order_upgrade_age
 The last age at which the eccentricity order was increased. More...
 
std::list< double > __tabulated_ages
 The ages at which solution is tabulated. More...
 
std::list< Core::EvolModeType__tabulated_evolution_modes
 The evolution mode corresponding to the matching tabulated age. More...
 
std::valarray< size_t > __skip_history_zerocrossing
 The number of points at the start of the history to skip when lookng for a zero crossing for each condition. More...
 
std::valarray< double > __skip_history_extremum
 The age after which to look for extrema for each condition. More...
 
std::list< double > __stop_history_ages
 The ages at which the stop condition history is kept. More...
 
std::list< double > __discarded_stop_ages
 The ages of steps which were discarded becauset they are past a zero or an extremum of a stopping condition . More...
 
std::list< std::valarray< double > > __orbit_history
 Past orbits. More...
 
std::list< std::valarray< double > > __orbit_deriv_history
 Past orbital derivatives. More...
 
std::list< std::valarray< double > > __stop_cond_history
 Past values of the stop conditions. More...
 
std::list< std::valarray< double > > __stop_deriv_history
 Past values of the stop condition derivatives. More...
 
std::list< std::valarray< double > > __stop_cond_discarded
 Discarded values of the stop conditions. More...
 
std::list< std::valarray< double > > __stop_deriv_discarded
 Discarded derivatives of the stop conditions. More...
 
StoppingCondition__stopping_conditions
 The current set of stopping conditions. More...
 
std::vector< StopInformation__stop_info
 
bool __print_progress
 See print_progress argument of constructor. More...
 
time_t __evolution_start_time
 When did the currently running evolution start. More...
 
double __runtime_limit
 Max number of seconds current evolution is allowed to run. More...
 

Detailed Description

Solves the system of ODEs describing the evolution of a single planet around a single star.

Definition at line 115 of file OrbitSolver.h.

Constructor & Destructor Documentation

◆ OrbitSolver()

Evolve::OrbitSolver::OrbitSolver ( double  max_age,
double  required_precision,
bool  print_progress = false 
)

Prepare to solve for the orbital evolution.

Parameters
max_ageThe end age for the evolution.
required_precisionThe precision which to require of the solution.
print_progressShould output be created to track the progress in calculating the evolution?

Definition at line 1387 of file OrbitSolver.cpp.

◆ ~OrbitSolver()

Evolve::OrbitSolver::~OrbitSolver ( )
inline

Clean up.

Definition at line 502 of file OrbitSolver.h.

Member Function Documentation

◆ acceptable_step()

bool Evolve::OrbitSolver::acceptable_step ( double  current_age,
double  previous_age,
const StopInformation stop_info 
)
private

Updates the skip_history_zerocrossing and skip_history_extremum arrays appropriately after an acceptable step.

Return true iff the step with the given stop information is acceptable.

Definition at line 650 of file OrbitSolver.cpp.

◆ add_to_evolution()

void Evolve::OrbitSolver::add_to_evolution ( double  age,
Core::EvolModeType  evolution_mode,
BinarySystem system 
)
private

Adds the last step to the evolution.

Parameters
ageThe age of the evolving stellar system.
evolution_modeThe evolution mode represented in orbit.
systemThe binary system being evolved.

Definition at line 158 of file OrbitSolver.cpp.

◆ adjust_eccentricity_order()

void Evolve::OrbitSolver::adjust_eccentricity_order ( BinarySystem system,
const std::valarray< double > &  orbit,
Core::EvolModeType  evolution_mode,
bool  must_increase = false 
)
private

Increase/decrease the eccentricity expansion order until error is acceptable and return the new order.

Parameters
systemThe system being evolved.
orbitThe current orbital elements.
evolution_modeThe evolution mode for this part of the evolution.
must_increaseIf true the eccentircity order is increased by at least 1.

Definition at line 1282 of file OrbitSolver.cpp.

◆ at_exact_condition()

bool Evolve::OrbitSolver::at_exact_condition ( double  previous_age,
const StopInformation stop_info 
)
private

Is the condition causing a stop match to within the required precision?

Definition at line 632 of file OrbitSolver.cpp.

◆ check_expansion_error()

int Evolve::OrbitSolver::check_expansion_error ( const std::valarray< double > &  derivatives,
const std::valarray< double > &  expansion_errors 
)
private

Return -1 if the expansion error is too small (e-order can safely be decreased, 0 if it is within range, 1 if it is too big.

Parameters
derivativesThe rates of change of the evolution variables per Gyr.
expansion_errorsThe errors in derivatives, due to the truncated eccentricity series.

Definition at line 681 of file OrbitSolver.cpp.

◆ clear_discarded()

void Evolve::OrbitSolver::clear_discarded ( )
private

Removes all stored discarded stop condition information.

Definition at line 135 of file OrbitSolver.cpp.

◆ clear_history()

void Evolve::OrbitSolver::clear_history ( )
private

Clears the current stopping condition history.

Definition at line 206 of file OrbitSolver.cpp.

◆ crossing_from_history()

double Evolve::OrbitSolver::crossing_from_history ( size_t  condition_index) const
private

Estimates the age at which a stopping condition with derivative information crossed zero.

If no zero-crossing is indicated, Inf is returned.

Parameters
condition_indexThe index of the condition to search.

Definition at line 532 of file OrbitSolver.cpp.

◆ crossing_from_history_no_deriv()

double Evolve::OrbitSolver::crossing_from_history_no_deriv ( size_t  condition_index) const
private

Estimates the age at which a stopping condition with no derivative information crossed zero.

If no zero-crossing is indicated, Inf is returned.

Parameters
condition_indexThe index of the condition to search.

Definition at line 483 of file OrbitSolver.cpp.

◆ evolution_ages()

const std::list<double>& Evolve::OrbitSolver::evolution_ages ( ) const
inline

The ages at which evolution has been tabulated so far.

Definition at line 494 of file OrbitSolver.h.

◆ evolve_until()

StopInformation Evolve::OrbitSolver::evolve_until ( BinarySystem system,
double &  max_age,
std::valarray< double > &  orbit,
StoppingConditionType stop_reason,
double  max_step,
Core::EvolModeType  evolution_mode 
)
private

Evolves a system until either some age cut-off is reached or some stopping condition crosses zero.

Appends each accepted step to tabulated_ages, tabulated_evolution_mode, tabulated_orbit and tabulated_deriv.

The return value is true if the last step finished after the stopping condition crossed zero and false if it ended before that.

Parameters
systemThe planet-star system to evolve.
max_ageThe age at which to stop this part of the evolution. On exit, it is overwritten with the age of the last accepted step.
orbitThe initial conditions. The contents depends on the value of evolution_mode. See #BinarySystem.differential equations for details.

On exit, it is overwritten with the orbit of the last accepted step.

Parameters
stop_reasonOn input should be the reason why the last evolution stopped. It should be NO_STOP if this is the first piece of evolution being calculated. On exit it is overwritten with the value appropriate for the next run.
max_stepThe maximum step that GSL is allowed to take.
evolution_modeThe evolution mode for this part of the evolution.

Definition at line 945 of file OrbitSolver.cpp.

◆ extremum_from_history()

ExtremumInformation Evolve::OrbitSolver::extremum_from_history ( size_t  condition_index) const
private

Estimates the value and age of an extremum of a stopping condition for which derivative information is available.

If no extremum is indicated by the points, or if it is in the wrong direction to cause a zero-crossing, returns the result of the default constructor of ExtremumInformation.

Definition at line 445 of file OrbitSolver.cpp.

◆ extremum_from_history_no_deriv()

ExtremumInformation Evolve::OrbitSolver::extremum_from_history_no_deriv ( size_t  condition_index) const
private

Estimates the value and age of an extremum of a stopping condition for which no derivative information is available.

If no extremum is indicated by the points, or if it is in the wrong direction to cause a zero-crossing, returns the result of the default constructor of ExtremumInformation.

Definition at line 313 of file OrbitSolver.cpp.

◆ get_stopping_condition()

CombinedStoppingCondition * Evolve::OrbitSolver::get_stopping_condition ( BinarySystem system)
private

Returns the stopping conditions which end the given evolution mode and update __stop_info.

Parameters
systemThe system being evolved.

Definition at line 1185 of file OrbitSolver.cpp.

◆ go_back()

double Evolve::OrbitSolver::go_back ( double  max_age,
BinarySystem system,
std::valarray< double > &  orbit 
)
private

Rewinds the evlution to the last step before the given age and returns the age of that step.

Sets the orbit to what it was at that step and removes any items from the histories and tabulations that are later than max_age.

Definition at line 168 of file OrbitSolver.cpp.

◆ initialize_skip_history()

void Evolve::OrbitSolver::initialize_skip_history ( const StoppingCondition stop_cond,
StoppingConditionType  stop_reason 
)
private

Initializes the skip_history_zerocrossing and skip_history_extremum arrays appropriately after a mode change.

Definition at line 587 of file OrbitSolver.cpp.

◆ insert_discarded()

void Evolve::OrbitSolver::insert_discarded ( double  age,
const std::valarray< double > &  current_stop_cond,
const std::valarray< double > &  current_stop_deriv 
)
private

Adds an entry in the discarded ages, stop conditions and derivatives.

Makes sure the ages remain ordered.

Definition at line 142 of file OrbitSolver.cpp.

◆ mode_evolution()

const std::list<Core::EvolModeType>& Evolve::OrbitSolver::mode_evolution ( ) const
inline

The tabulated evolution modes so far.

Definition at line 498 of file OrbitSolver.h.

◆ operator()()

void Evolve::OrbitSolver::operator() ( BinarySystem system,
double  max_step = Core::Inf,
const std::list< double > &  required_ages = std::list<double>(),
double  max_runtime = 0 
)

Actually solves the given differential equation with the given boundary conditions.

Parameters
systemThe stellar system to calculate the evolution for
max_stepThe maximum size of the time steps allowed (useful if finer sampling of the output than default is necessary).
required_agesA sorted list of ages to include in the tabulated evolution.
max_runtimeThe maximum amount of wall-clock time in seconds to allow for calculating the evolution. If it runs out, whatever portion is calculated is preserved.

Definition at line 1401 of file OrbitSolver.cpp.

◆ output_history_and_discarded()

void Evolve::OrbitSolver::output_history_and_discarded ( std::ostream &  os)
private

Generates a nicely formatted table of the contents of the discarded and history stopping condition information.

Only exists if NDEBUG is not #defined.

Definition at line 55 of file OrbitSolver.cpp.

◆ reached_stopping_condition()

void Evolve::OrbitSolver::reached_stopping_condition ( double  stop_age,
StoppingConditionType  stop_reason 
)
private

Handle a stop in the evolution due to at least one condition reaching a critical value.

Assumes that __stop_info was updated per the last accepted step.

Parameters
stop_ageThe age of the last accepted evolution step.
stop_reasonThe type of condition which caused the stoppage.

Definition at line 1238 of file OrbitSolver.cpp.

◆ reject_step()

void Evolve::OrbitSolver::reject_step ( double &  age,
StopInformation stop,
BinarySystem system,
std::valarray< double > &  orbit,
double &  max_next_t,
double &  step_size,
std::string  reason 
)
private

Handle the situation when the last step has to be rejected.

Parameters
ageThe age up to which the rejected step reached, on exit gets updated with the last acceptable age found.
stopThe reason we stopped. If a zero-crossing, the precision is updated.
systemThe binary system being evolved.
orbitThe current orbit of the system, gets updated with the last acceptable orbit found.
max_next_tGets updated with the maximum age up to which evolution is allowed to proceed.
step_sizeGets updated with the step size to use for the next step.The reason for rejecting the step.

Definition at line 893 of file OrbitSolver.cpp.

◆ reset()

void Evolve::OrbitSolver::reset ( BinarySystem system)
private

Clears any previously calculated evolution.

Definition at line 1380 of file OrbitSolver.cpp.

◆ select_stop_condition_interval()

StopHistoryInterval Evolve::OrbitSolver::select_stop_condition_interval ( bool  crossing,
size_t  cond_ind,
size_t  max_points 
) const
private

Selects a history interval for interpolating to a reason to stop the evolution.

Finds the smallest possible interval that contains a zero crossing/or an extremum straddling the history and discarded stop conditions, containing at most the specified number of points (could be less if there are not enough points). The interval is also guaranteed to contain at least one point in the history and one point in the discarded list.

Definition at line 216 of file OrbitSolver.cpp.

◆ stopping_age()

double Evolve::OrbitSolver::stopping_age ( double  age,
const BinarySystem system,
const std::list< double > &  required_ages 
)
private

The age at which the evolution should stop next if no other stopping condition occurs.

Parameters
ageThe age from which the next part of the evolution starts.
systemThe stellar system being evolved.
required_agesA sorted list of ages which must be stopped at.

Definition at line 1203 of file OrbitSolver.cpp.

◆ update_stop_condition_history()

StopInformation Evolve::OrbitSolver::update_stop_condition_history ( double  age,
const std::valarray< double > &  orbit,
const std::valarray< double > &  derivatives,
const std::valarray< double > &  expansion_errors,
Core::EvolModeType  evolution_mode,
StoppingConditionType  stop_reason = NO_STOP,
bool  ignore_e_order_decrease = false 
)
private

Updates stop_cond_history and stop_deriv_history after a GSL step, returning if/where the evolution needs to stop.

Returns the index of the condition with the closest estimated age for zero crossing or an extremum exists which might have crossed zero.

Parameters
ageSystem age in Gyr.
orbitThe values of the current evolution variables.
derivativesThe rates of change of the evolution variables per Gyr.
expansion_errorsThe errors in derivatives, due to the truncated eccentricity series.
evolution_modeThe current evolution mode.
stop_reasonFor the first call of this function for an evolution stretch, this should indicate the reason why the previous stretch was stopped. For subsequent calls during the same evolution stretch it should be NO_STOP.
ignore_e_order_decreaseIf true, ignore indication that eccentricity order should be decreased.

Definition at line 735 of file OrbitSolver.cpp.

Member Data Documentation

◆ __discarded_stop_ages

std::list<double> Evolve::OrbitSolver::__discarded_stop_ages
private

The ages of steps which were discarded becauset they are past a zero or an extremum of a stopping condition .

Definition at line 146 of file OrbitSolver.h.

◆ __e_order_downgrade_threshold

double Evolve::OrbitSolver::__e_order_downgrade_threshold
private

If the fractional error due to truncating the eccentricity series falls below this value times the maximum acceptable error, the eccentricity order is downgraded.

Definition at line 119 of file OrbitSolver.h.

◆ __end_age

double Evolve::OrbitSolver::__end_age
private

The last age for which evolution is required.

Definition at line 119 of file OrbitSolver.h.

◆ __evolution_start_time

time_t Evolve::OrbitSolver::__evolution_start_time
private

When did the currently running evolution start.

Definition at line 181 of file OrbitSolver.h.

◆ __last_e_order_upgrade_age

double Evolve::OrbitSolver::__last_e_order_upgrade_age
private

The last age at which the eccentricity order was increased.

Definition at line 119 of file OrbitSolver.h.

◆ __orbit_deriv_history

std::list< std::valarray<double> > Evolve::OrbitSolver::__orbit_deriv_history
private

Past orbital derivatives.

Definition at line 153 of file OrbitSolver.h.

◆ __orbit_history

std::list< std::valarray<double> > Evolve::OrbitSolver::__orbit_history
private

Past orbits.

Definition at line 153 of file OrbitSolver.h.

◆ __precision

double Evolve::OrbitSolver::__precision
private

The precision required of the solution.

Definition at line 119 of file OrbitSolver.h.

◆ __print_progress

bool Evolve::OrbitSolver::__print_progress
private

See print_progress argument of constructor.

Definition at line 178 of file OrbitSolver.h.

◆ __runtime_limit

double Evolve::OrbitSolver::__runtime_limit
private

Max number of seconds current evolution is allowed to run.

Definition at line 184 of file OrbitSolver.h.

◆ __skip_history_extremum

std::valarray<double> Evolve::OrbitSolver::__skip_history_extremum
private

The age after which to look for extrema for each condition.

Definition at line 143 of file OrbitSolver.h.

◆ __skip_history_zerocrossing

std::valarray<size_t> Evolve::OrbitSolver::__skip_history_zerocrossing
private

The number of points at the start of the history to skip when lookng for a zero crossing for each condition.

Definition at line 140 of file OrbitSolver.h.

◆ __stop_cond_discarded

std::list< std::valarray<double> > Evolve::OrbitSolver::__stop_cond_discarded
private

Discarded values of the stop conditions.

Useful for interpolating to zeroes and extrema.

Definition at line 153 of file OrbitSolver.h.

◆ __stop_cond_history

std::list< std::valarray<double> > Evolve::OrbitSolver::__stop_cond_history
private

Past values of the stop conditions.

Definition at line 153 of file OrbitSolver.h.

◆ __stop_deriv_discarded

std::list< std::valarray<double> > Evolve::OrbitSolver::__stop_deriv_discarded
private

Discarded derivatives of the stop conditions.

Useful for interpolating to zeroes and extrema.

Definition at line 153 of file OrbitSolver.h.

◆ __stop_deriv_history

std::list< std::valarray<double> > Evolve::OrbitSolver::__stop_deriv_history
private

Past values of the stop condition derivatives.

Definition at line 153 of file OrbitSolver.h.

◆ __stop_history_ages

std::list<double> Evolve::OrbitSolver::__stop_history_ages
private

The ages at which the stop condition history is kept.

Definition at line 146 of file OrbitSolver.h.

◆ __stop_info

std::vector<StopInformation> Evolve::OrbitSolver::__stop_info
private

The full information about the next age where each stopping condition indicates evolution should be stopped and why.

Definition at line 175 of file OrbitSolver.h.

◆ __stopping_conditions

StoppingCondition* Evolve::OrbitSolver::__stopping_conditions
private

The current set of stopping conditions.

Definition at line 171 of file OrbitSolver.h.

◆ __tabulated_ages

std::list<double> Evolve::OrbitSolver::__tabulated_ages
private

The ages at which solution is tabulated.

Definition at line 133 of file OrbitSolver.h.

◆ __tabulated_evolution_modes

std::list<Core::EvolModeType> Evolve::OrbitSolver::__tabulated_evolution_modes
private

The evolution mode corresponding to the matching tabulated age.

Definition at line 136 of file OrbitSolver.h.


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