many_equilibria

many_equilibria

This project allows a user to compute a variety of equilibria over a range of conditions and to apply a user-defined function.

Installing the project.

If you have not previously done so, install the necessary [libraries]. Next, if you have not previously done so, create a projects directory:

** mkdir projects **

Change into the projects directory:

** cd projects **

Now you can checkout the project:

** svn checkout svn://svn.code.sf.net/p/nucnet-projects/code/trunk/projects/many_equilibria**

Compiling the executables.

Change into the project directory:

** cd many_equilibria **

Now select the default user function file by typing

cp default/many_eq_user_function.cpp .

and compile the codes by typing

** ./project_make **

The project compiled successfully if you see Make succeeded. Otherwise, please submit a Ticket or make a post to the Discussion board (see links above).

Obtaining a usage statement.

Once the programs have compiled, you can obtain a usage statement by typing

./compute_many_equil

That will list the top-level options. To get usage options on the t9 grid, for example, type

./compute_many_equil --help-module t9

This will list the options to establish the t9 grid. You may similiarly obtain options for the density (rho) and electron fraction (Ye) grid by typing

./compute_many_equil --help-module rho

and

./compute_many_equil --help-module Ye

To get the options for the network, type

./compute_many_equil --help-module network

To get the user-defined options, type

./compute_many_equil --help-module user

The user-defined options will depend on the particular user-supplied application function file. In all cases, default values for options are shown in parentheses.

Printing equilibrium abundances versus temperature, density, and electron fraction (Ye).

You will need nuclear data. To obtain the default data, type

** make data**

Once the data are available, you can compute, for example, the NSE abundance of ⁵⁶Ni, ⁵⁷Ni, and ⁵⁸Ni in the temperature range T₉ = T / 10⁹ K = 5 to 10 and the mass density range ρ = 10⁵ to 10¹⁰ g/cc for an electron-to-nucleon ratio Y_e = 0.5 by typing

** ./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml --t9_min 5 --t9_max 10 --t9_points 15 --rho_min 1.e5 --rho_max 1.e10 --rho_points 15 --rho_log logarithmic --ye_min 0.5 --ye_max 0.5 --ye_points 1 --species ni56 --species ni57 --species ni58 --nuc_xpath "[z <= 50]"**

In the above, we choose a temperature grid with 15 points, a logarithmic density grid with 15 points, and a Ye grid with only one point. Species to print out are selected with a arbitrary number of species options. The XPath expression "[z <= 50]" selects only nuclei with atomic number less than or equal to 50 for the calculation. To use all nuclei, you can omit this expression or choose "". The output contains columns with, respectively, T₉, ρ, Y_e, the mass fraction of ⁵⁶Ni, ⁵⁷Ni, and ⁵⁸Ni.

We may collect many of the options into a response file. For example, one can create a file data.rsp that has the lines

--t9_min 5 --t9_max 10 --t9_points 15 --rho_min 1.e5
--rho_max 1.e10 
--rho_points 15 --rho_log logarithmic --ye_min 0.5
--ye_max 0.5 --ye_points 1 
--species ni56 
--species ni57 
--species ni58

We then rerun the above calculation and redirect the output from the above calculation into a file ni.txt by typing

** ./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml @data.rsp --nuc_xpath "[z <= 50]" > ni.txt**

Notice that I do not include the XPath option in the response file.

I can arbitrarily constrain the abundances through equilibrium clusters. To compute, for Y_e = 0.45, the quasi-equilibrium abundance of ⁴⁰Ca as a function of the above temperature and density range (but with an 8 x 8 grid) when Y_h, the abundance of heavy nuclei (nuclei with Z > 2), is constrained to be 0.02, type

./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml --t9_min 5 --t9_max 10 --t9_points 8 --rho_min 1.e5 --rho_max 1.e10 --rho_points 8 --rho_log logarithmic --ye_min 0.5 --ye_max 0.5 --ye_points 1 --species ca40 --nuc_xpath "[z <= 50]" --cluster "[z > 2]:0.02"

Here I provide the QSE constraint with the cluster option in the form XPath expression:abundance constraint. I can provide an arbitrary number of cluster constraints. I can also again use a response file, but the nuc_xpath and cluster options must not be in the file but rather must be included in the command line.

Printing equilibrium average Z and A versus temperature and density.

Another example user function that may be applied in a calculation of many equilibria is one that prints out the abundance of nuclei, the average atomic number Z, and the average mass number A. To run such a calculation in a bash shell, set the environment variable MANY_EQ_FUNC to av by typing

export MANY_EQ_FUNC=av

Next, clean the default user-supplied function by typing

make clean

Now you can remake the codes by typing

./project_make

Once the program has compiled, note that

./compute_many_equil --help-module user

returns no options since none are used in this version of the program.

Run the appropriate code for the NSE conditions above by typing

./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml --t9_min 5 --t9_max 10 --t9_points 15 --rho_min 1.e5 --rho_max 1.e10 --rho_points 15 --rho_log logarithmic --ye_min 0.5 --ye_max 0.5 --ye_points 1 --nuc_xpath "[z <= 50]"

The output columns are T₉, ρ, Y_e, Y, the abundance of nuclei per nucleon, ⟨Z⟩, the average atomic number of the nuclei, and ⟨A⟩, the average mass number of the nuclei.

You can also redirect output, use a response file, or add equilibrium constraints as described above. To reset the applied function to the default (printout of the abundance of a particular species), clear the environment variable, clean the default user-supplied function, and remake:

unset MANY_EQ_FUNC

make clean

./project_make

Saving an output XML file.

The third default example writes an output XML file containing the data for each (T₉, ρ, Y_e) triplet as a libnucnet zone. To create this example, type

export MANY_EQ_FUNC=xml

make clean

./project_make

To compute the above equilibrium temperature, density, Ye range and save the output to a file my_output.xml, type

./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml --t9_min 5 --t9_max 10 --t9_points 15 --rho_min 1.e5 --rho_max 1.e10 --rho_points 15 --rho_log logarithmic --ye_min 0.5 --ye_max 0.5 --ye_points 1 --nuc_xpath "[z <= 50]" --output_xml my_output.xml

As before, you can also redirect output, use a response file, or add equilibrium constraints as described above.

Supplying your own function.

It is possible to supply your own function to be applied in the calculation of the many equilibria. To do this, write your own many_eq_user_function.cpp and copy it to the many_equilibria directory. Then compile.

Your many_eq_user_function.cpp must contain the following four routines:

1) A routine called get_user_defined_descriptions() that describes any options your function needs. The prototype is

    void get_user_defined_descriptions( po::options_description& );

po::options_description is the Boost class containing information about program options.

2) A routine called set_user_defined_options() that sets the options as data for your function. The prototype is

    void set_user_defined_options( po::variables_map&, equil_data_t& );

po:variables_map is the Boost program options variable map and equil_data_t is a map containing a key and an arbitrary data type that the user casts.

3) The user-defined function called user_function() applied to the computed equilibria. The prototype is

     void user_function( Libnucnet *, Libnuceq *, equil_data_t& );

The first argument is a pointer to a Libnucnet structure, the second is a pointer to a Libnuceq structure, and the third is the data map mentioned previously.

4) A routine called user_output_data() to output data at the end of a calculation. The prototype is

     void user_output_data( Libnucnet *, equil_data_t& );

The arguments for this routine have been previously described.

The many_eq_user_function.cpp in the directory other_example provides an example. That example computes the rate of change of Y_e in equilibrium, including the possibility of using the approximate weak rates presented by Arcones et al.

Copy your many_eq_user_function.cpp into the many_equilibria directory. For the present example, type

cp other_example/many_eq_user_function.cpp .

Now make the codes:

./project_make

You can then run your version. To run the present example for a T₉ = 8, a mass density of ρ = 10⁹ g/cc, and grid of 100 points for Y_e between 0.4-0.5 by typing

./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml --t9_min 8 --t9_points 1 --rho_min 1.e9 --rho_points 1 --ye_min 0.4 --ye_max 0.5 --ye_points 100 --nuc_xpath "[z <= 50]" --reac_xpath none --use_approx_weak_rates --munuekT 1.

Here the reac_xpath is a reaction XPath that selects out no reactions from the input my_net.xml. The option use_approx_weak_rates then updates the network with the Arcones et al. approximate weak rates. The option munuekT sets the electron neutrino chemical potential divided by kT (in this case, to the value of 1). The default value for munuekT is -inf, which is the appropriate value for free-streaming neutrinos.

The output columns are T₉, ρ, Y_e, the total beta-minus decay rate, the total beta-plus decay rate, the total electron-capture rate, the total positron-capture rate, and the total rate of change of Y_e.

Again, with a properly defined many_eq_user_function.cpp, it is possible to redirect output, use a response file, or add equilibrium constraints as described above.