Extending MESA++
This page describes how to implement your own physics through
inheritance of the MESA++
Star class.
How is physics specified in Star?
How to add your own physics
How is physics specified in Star?
The MESA++ Star class
supports the same standard physics options as MESA, since a Star is created from a standard
MESA inlist. However, one of the options for most kinds of
physics is "other", which tells MESA (and MESA++ Star) to use whatever extension
has been provided by the developer. In MESA, these extensions take the form of functions the developer writes and then installs as procedure pointers in the star_info object. The developer can also request extra storage in the star_info object and extra columns of output in restart and log files.
Star simplifies this process a bit by automating a lot of this machinery. For example, for extra mass loss or accretion, Star defines a virtual function:
virtual void other_wind_(double &w) throw (Mesa_Exception)
{
// by default, sheds no extra mass
w = 0;
}
that computes the amount of extra mass loss. There are corresponding options for mixing, energy, and equation of state. Since there is no meaningful default for equation of state, the default behavior of these functions is to throw an exception.
The details of how Star hooks these functions up where the MESA evolution codes will use them need not concern us much here. Suffice it to say that it's all done in the constructor for Star.
How to add your own physics
Suppose you have your own mass loss model you wish to use with Mesa++ Star. You simply define a child
class of Star that
overrides this virtual function with one that returns whatever mass
loss you wish to compute. Your class could be as simple as:class MyStar : public Star
{
public:
//***** OBJECT MANAGEMENT
MyStar(string const &inlist)
{
create(inlist);
}
MyStar(string const &inlist, string const &restart_file)
{
restart(inlist, restart_file)
}
protected:
virtual void other_wind_(double &w) throw (Mesa_Exception)
{
// insert code here to compute your mass loss rate;
}
};
The only "gotcha" is that you must always use the default constructor for Star in the constructors for your child class, then use Star::create or Star::restart to complete the construction process. The reason for this is a subtlety of how C++ constructors work: Virtual functions calls are disabled during construction, in the sense that a call to a virtual function in a constructor always takes you to the version for the class currently being constructed rather than any overriding version. Thus, we must defer initialization to the constructor for the child class to ensure all the new physics is in place.
The Star::create and Star::restart functions take care of all the tasks required to hook up the virtual functions to the underlying star_info object so they are called at the appropriate time. If you need to access the underlying star_info, it is accessible via the member function Star::s(), which returns a pointer to star_info.
If you need additional storage for your model, my recommendation is to allocate the storage in your child class of Star rather than using the extra_work and extra_iwork facilities in the star_info object itself. However, I'm still mulling over the right way to do this.
If you have data you want included in restarts, you will need to to override load_restart_ and save_restart_. Your overrides should explicitly call the base functions to ensure that storage for the base Star class is properly saved or loaded:
void MyStar::save_restart_(FILE *file) const
{
Star::save_restart_(file); // save base Star information
// now save whatever data MyStar needs to save in restart files:
fwrite(&my_data, sizeof(my_data), 1, file):
// etc.
}
void MyStar::load_restart_(FILE *file) throw (Mesa_Exception)
{
Star::load_restart_(file); // save base Star information
// now save whatever data MyStar needs to save in restart files:
fread(&my_data, sizeof(my_data), 1, file):
// etc.
}
You should check that there are no errors reading the restart file, and throw a Mesa_Exception if any such errors are encountered.
Note that the FILE comes in already open and correctly positioned, and you should not close it or reposition it in any way (other than by writing or reading to it.)
A more complete example of creating your own custom star modeling class by inheritance from Star can be found in the MESA++ distribution as the files
mesapp/star/src/MyStar.hh
mesapp/star/src/MyStar.cc
website
design
by
Andreas Viklund