evolve_utility Namespace Reference

Classes
class	EvolveBBH
class	EvolveBCX1
class	EvolveBHMS
class	EvolveBHMSTarantula
class	EvolveBinaryCompact
class	EvolveBinaryCompactOld
class	EvolveBLC
class	EvolveDebug
class	EvolveDefault
class	EvolveFunctor
class	EvolveRecordCondition
class	EvolveRRL
class	EvolveStopCondition
class	EvolveW1
struct	Options

Functions
int	evolve_single (Binstar &binary, SevnLogging &svlog, bool record_state=true)
int	evolve_single (Star &star, SevnLogging &svlog, bool record_state=true)
template<typename System >
int	evolve_list (EvolveFunctor *evolve_function, std::vector< System > &systems, _UNUSED IO &sevnio, int Nevolve=-1)
template<typename T >
int	chunk_dispatcher (unsigned int Nchunk, IO &sevnio, std::vector< T > &systems, bool record_state=true, bool progress=true)
template<typename T >
int	chunk_dispatcher (EvolveFunctor *evolve_function, unsigned int Nchunk, IO &sevnio, std::vector< T > &systems, bool progress=true)

Detailed Description

IDEA BEHIND THE EVOLVE FUNCTOR

The Evolve Functors are used to handle the evolution, the record of properties and the output of both stars and binaries. The evolve function of the classes Star and Binaries just evolves the system of a single adaptive timestep forward, the Evolve fuctor described here have the role to drive the complete evolution stopping it when needed, print in in output the results and handle errors. The Base EvolveFunctor constructor has 4 parameters:

• Reference to Sevnlogging istance: it is used to initialise the protected member _svlog svlog is used to return logs (debug, info, errors) in the class. Use always it to return infos to the standard output or raise errors.
• bool record_state: it is used to initialise the protected member _record_state. if this parameter is true, all the states record and print has to be disabled
• bool include_failed> it is used to initialse the protected member _include_failed. if _include_failed is true, we have to print to the output files also for star with failed evolution
• Options *option: pointer to the struct Options, it is used to initialise the protected member _options this struct containt a vector of doubles and a vector of string. This is an optional member (it set to nullptr by default) used to add other parameters for a given Functor.

The key method of a Functor is the override of the operators(Binstar& binstar) and operators(Star& star). This is the function that perform the actual evolution. As a general guide the evolve should contain an infinite for that call star or binstar evolution.

** CHECK STALLING ** At beginning of each evolution step the check for stalling should be added through the static method check_stalling(system). System could be both a Star or a binary, for example check_stalling(binary) or check_stalling(star). Notice that the method is static so it could (and should be called) also for custom evolution functions: EvolveFunctor::check_stalling(binary) or EvolveFunctor::check_stalling(star). The method returns a sevnerror if the binary or the stars has been evolving for more a time set at runtime through the propertis check_stalling_time. The check can be disabled at runtime by using -check_stalling false

After the evolution it should be checked if the breaktrigger condition have been reached. In that case the for cycle is stopped through a break. Inside the for it should be checked also if the condition for record of the states has been reached. If this is the case we have to call the method recordstate_w_timeupdate(). The method records the states and update the property NextOutput. Notice that if the memmber _record_state is false, the states should be never recorded indepentely from the input and EvolveFunctor options. If we want to handle the errors without stopping the whole computation we have to use a try .. catch .. structure. The evolution is inserted inside the try part while inside the catch we have to set the member evolution_results=EXIT_FAILURE; and a brak for the for cycle should be inserted. At the end of the function before we have to add the mandatory following lines: final_print(system); //Handle the output printing return _evolution_result; //Exit_SUccess (default) or EXIT_FAILURE if it has been set in the evolution (if the evolution failed).

HOW TO ADD A NEW EVOLVE FUNCTION

The evolve function is a Functor that should have two mandatory override operator:

• inline int operator() (Binstar& binary)
• inline int operator() (Star& star) The constructor need to call the base class constructor (that has parameters svlog and record_state).

Implementation steps Assume we are implementing a new evolve functor EvolveNizzi 1- Create a class derived from the the base class EvolveFunctor class EvolveNizzi : public EvolveFunctor 2- Implement the class constructor that calls the base class constructor

  EvolveNizzi(SevnLogging& svlog, bool record_state=true) : EvolveFunctor(svlog,record_state) {...}
  @param svlog, instance of class Svlogging
  @param record_state, If true enable the state recording during the evolution (following the parameters in input)

3- Override the pure virtual operator () for both stars and binstars

• inline int operator() (Binstar& binary) override {....}
• inline int operator() (Star& star) override {....} These are the function that will be actually called to perform the evolution of a star or a binary NOTICE: if the function is the same for both Star and Binstar it is better to implement a separate (protected of private) template function that will be called inside the operator. REMEMBER to add the check for stalling inside the evolution function at the beginning of each evolution step (see above): check_stalling(binary) or check_stalling(star). e.g. protected: template <typename System> inline int evolve_common(System& system){...}

and then

public: inline int operator() (Binstar& binary) override { return evolve_common(binary);} inline int operator() (Star& star) override { return evolve_common(star);}

     NOTICE: The functions have to return EXIT_SUCCESS if the evolution ended without problems or EXIT_FAILURE or
     raise an Error in the other cases

WRITE DOCUMENTATION OF THE CLASS The documentation of new EvolveFunctor should follow the schema:

• A brief description of the Evolve purpose
• @record_state_policy: Describe when the states are recorded and how the dtout in input is used and interpreted
• @break_evolve_policy: Describe when the evolution is halted and how the tf in input is used and interpreted
• @Extra_options: It the struct Options is used for extra input options, describe these extra parameters.
• @binstar_evolve: If the evolve can be applied to binaries write Yes, otherwise give information (e.g. what kind of error is raised)
• @star_evolve: If the evolve can be applied to stars write Yes, otherwise give information (e.g. what kind of error is raised)
• @catch: Write what kind of errors (if any) is catched during the evolve sequence

HOW TO USE IT IN THE MAIN FUNCTION

• Create a pointer to the given Functor e.g. evolve_utility::EvolveFunctor* evolve_function = new evolve_utility::EvolveNizzi(svlog,true);
• Use directly the function ( (*evolve_function)(binstar) ) or use it as parameter in the chunk_dispatcher: e.g. evolve_utility::chunk_dispatcher(evolve_function,Nchunk,sevnio,stars,true);
• If the function is stoared in the heap, remember to delete the pointer after the evolution e.g. delte evolve_function.

Function Documentation

chunk_dispatcher() [1/2]

template<typename T >

int evolve_utility::chunk_dispatcher ( EvolveFunctor *  evolve_function, unsigned int  Nchunk, IO &  sevnio, std::vector< T > &  systems, bool  progress = true  )

inline

Evolve using chunk version with functor

Template Parameters

T	It could be Binstar or Star

Parameters

evolve_function	Pointer to functor derived from base class EvolveFunctor
Nchunk	Number of systems to evolve in each chunk
sevnio	Instance of the IO class (the one linked to the binaries)
systems	Vector containing the systems to evolve.
progress	If true print progress information to the standard output

Returns

Number of failed evolutions @Note The vector of systems is passed by reference and it is cleared if not empty yet.

Preliminary reset

Preliminary assignment

Cycle

chunk_dispatcher() [2/2]

template<typename T >

int evolve_utility::chunk_dispatcher ( unsigned int  Nchunk, IO &  sevnio, std::vector< T > &  systems, bool  record_state = true, bool  progress = true  )

inline

Evolve using chunk

Template Parameters

T	It could be Binstar or Star

Parameters

Nchunk	Number of systems to evolve in each chunk
sevnio	Instance of the IO class (the one linked to the binaries)
systems	Vector containing the systems to evolve.
record_state	If true record and print the systems states (accordingly with the option parameters)
progress	If true print progress information to the standard output

Returns

Number of failed evolutions @Note The vector of systems is passed by reference and it is cleared if not empty yet.

Preliminary reset

Preliminary assignment

Cycle

evolve_list()

template<typename System >

int evolve_utility::evolve_list ( EvolveFunctor *  evolve_function, std::vector< System > &  systems, _UNUSED IO &  sevnio, int  Nevolve = -1  )

inline

Evolve a list of stars or binstars

Template Parameters

System

It could be Binstar or Star

Parameters

evolve_function	Pointer to functor derived from base class EvolveFunctor
systems	Vector containing the systems to evolve.
sevnio	Instance of the IO class (the one linked to the binaries)
Nevolve	Number of systems to evolve (first Nevolve). If -1 evolve all the sytems

Returns

Number of failed evolutions

evolve_single() [1/2]

int evolve_utility::evolve_single ( Binstar &  binary, SevnLogging &  svlog, bool  record_state = true  )

inline

Evolve a binary system DEPREACATED

Parameters

binary	Binary system to evolve
svlog	Instance of the Sevenlogging class
record_state	If true record and print the binary states (accordingly with the option parameters)

Returns

EXIT_SUCCESS if the evolution is ended without errors. EXIT_FAILURE is sevnerr is raised. In that case the error is catched and an error message is printed in the stardard error output (but the run is not halted)

evolve_single() [2/2]

int evolve_utility::evolve_single ( Star &  star, SevnLogging &  svlog, bool  record_state = true  )

inline

Evolve a star

Parameters

star	Star system to evolve
svlog	Instance of the Sevenlogging class
record_state	If true record and print the binary states (accordingly with the option parameters)

Returns

EXIT_SUCCESS if the evolution is ended without errors. EXIT_FAILURE is sevnerr is raised. In that case the error is catched and an error message is printed in the stardard error output (but the run is not halted)