Recent changes to many_equilibria

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 08 Oct 2016 15:25:21 -0000

--- v12
+++ v13
@@ -58,7 +58,7 @@

 **`./compute_many_equil --help-module user`**

-The user-defined options will depend on the particular user-supplied application function file.
+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). #####

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sun, 31 Jul 2016 15:42:37 -0000

--- v11
+++ v12
@@ -92,7 +92,7 @@

 **`./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:abunandance 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.
+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. #####

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 30 Jul 2016 21:11:19 -0000

--- v10
+++ v11
@@ -184,7 +184,7 @@

 **`./project_make`**

-You can 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
+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.`**

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 30 Jul 2016 21:07:58 -0000

--- v9
+++ v10
@@ -22,31 +22,77 @@

 ** `cd many_equilibria` **

-and compile the codes:
+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).

-##### Printing equilibrium abundances versus temperature and density. #####
+##### 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.
+
+##### Printing equilibrium abundances versus temperature, density, and electron fraction (Ye). #####

 You will need nuclear data.  To obtain the [default data](https://sourceforge.net/u/mbradle/blog/2012/10/merging-nuclear-and-reaction-data/), type

 ** `make data`**

-Once the data are available, you can compute, for example, the [NSE](https://sourceforge.net/u/mbradle/blog/2012/09/calculating-nuclear-statistical-equilibrium/) abundance of ⁵⁶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
+Once the data are available, you can compute, for example, the [NSE](https://sourceforge.net/u/mbradle/blog/2012/09/calculating-nuclear-statistical-equilibrium/) 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 5. 10. 1.e5 1.e10 0.5 ni56 "[z <= 50]"`**
+** `./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]"`**

-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₉*, *ρ*, and the mass fraction of *⁵⁶Ni*.  To redirect the output from the above calculation into a file *ni56.txt*, type
+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*.  

-** `./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.5 ni56 "[z <= 50]" > ni56.txt`**
+We may collect many of the options into a *response file*.  For example, one can create a file *data.rsp* that has the lines

-To compute, for Y_e = 0.45, the quasi-equilibrium abundance of ⁴⁰Ca as a function of the above temperature and density range when Y_h, the abundance of heavy nuclei (nuclei with Z > 2), is constrained to be 0.02, type
+    --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

-**`./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.45 ca40 "" "[z > 2]" 0.02`**
+We then rerun the above calculation and redirect the output from the above calculation into a file *ni.txt* by typing

-Notice in this case that I must include the XPath expression on the nuclei, which, in this case, I choose *""* to include all nuclei.  The constraint and the larger number of nuclei included in this calculation will make it run slower than the NSE calculation above.  If possible, you will probably want to limit the nuclei involved with a more restrictive XPath expression.
+** `./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:abunandance 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. #####

@@ -56,54 +102,94 @@

 Next, clean the default user-supplied function by typing

-**`make cleanall_my_user`**
+**`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 5. 10. 1.e5 1.e10 0.5 "[z <= 50]"`**
+**`./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*, the abundance of nuclei per nucleon, *⟨Z⟩*, the average atomic number of the nuclei, and *⟨A⟩*, the average mass number of the nuclei.
+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 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:
+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 cleanall_my_user`**
+**`make clean`**

 **`./project_make`**

-##### Supplying your own function. #####
+##### Saving an output XML file. #####

-It is possible to supply your own function to be applied in the calculation of the many equilibria.  The simplest way to do this is to write your own *many_eq_user_function.cpp* and *many_eq_user_function.h* based on the examples in the directory *my_user_extra*.  Those examples compute the rate of change of Y_e as computed from approximate weak rates presented by [Arcones et al](http://adsabs.harvard.edu/abs/2010A%26A...522A..25A).
+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

-First, make sure that you have created a *my_user* directory.  This is done automatically in the steps above, so you might just want to type
+**`export MANY_EQ_FUNC=xml`**
+
+**`make clean`**

 **`./project_make`**

-Then copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* into *my_user*.  For example, you can type, in the *many_equilibria* directory,
+To compute the above equilibrium temperature, density, Ye range and save the output to a file *my_output.xml*, type

-**`cp my_user_extra/many_eq_user_function.* ../nucnet-tools-code/my_user/`**
+**`./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`**

-Then set the environment variable MANY_EQ_FUNC to *mine*:
+As before, you can also redirect output, use a response file, or add equilibrium constraints as described above. 

-**`export MANY_EQ_FUNC=mine`**
+##### 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](http://libnucnet.sourceforge.net/libnucnet/current/html/Libnucnet_h.html) structure, the second is a pointer to a [Libnuceq](http://libnuceq.sourceforge.net/libnuceq/current/html/Libnuceq_h.html) 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](http://adsabs.harvard.edu/abs/2010A%26A...522A..25A).
+
+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 run the appropriate code (for the NSE conditions described above) by typing
+You can 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 5. 10. 1.e5 1.e10 0.5 -inf "[z <= 50]"`**
+**`./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.`**

-The *-inf* is the electron neutrino chemical potential / kT--it can be any number greater than or equal to *-inf* and less than *inf*.  The output columns are *T₉*, *ρ*, 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.
+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.

-To use your own function, copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* to *my_user* and follow the above steps.  Do not type
+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.

-**`make cleanall_my_user`**
-
-unless you want to remove your functions.  The directory *nucnet-tools-code/my_user* is not version controlled by NucNet Tools, so you can version control its contents in your own repository, if you wish.
+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.

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sun, 30 Mar 2014 15:23:32 -0000

--- v8
+++ v9
@@ -104,6 +104,6 @@

 To use your own function, copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* to *my_user* and follow the above steps.  Do not type

-**`make cleanll_my_user`**
+**`make cleanall_my_user`**

 unless you want to remove your functions.  The directory *nucnet-tools-code/my_user* is not version controlled by NucNet Tools, so you can version control its contents in your own repository, if you wish.

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 21 Dec 2013 14:26:36 -0000

--- v7
+++ v8
@@ -100,7 +100,7 @@

 **`./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.5 -inf "[z <= 50]"`**

-The *-inf* is the electron neutrino chemical potential / kT--it can be any greater than or equal to *-inf* and less than *inf*.  The output columns are *T₉*, *ρ*, 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.
+The *-inf* is the electron neutrino chemical potential / kT--it can be any number greater than or equal to *-inf* and less than *inf*.  The output columns are *T₉*, *ρ*, 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.

 To use your own function, copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* to *my_user* and follow the above steps.  Do not type

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 23 Nov 2013 16:29:39 -0000

--- v6
+++ v7
@@ -100,7 +100,7 @@

 **`./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.5 -inf "[z <= 50]"`**

-The *-inf* is the electron neutrino chemical potential / kT.  The output columns are *T₉*, *ρ*, 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.
+The *-inf* is the electron neutrino chemical potential / kT--it can be any greater than or equal to *-inf* and less than *inf*.  The output columns are *T₉*, *ρ*, 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.

 To use your own function, copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* to *my_user* and follow the above steps.  Do not type

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 23 Nov 2013 16:24:13 -0000

--- v5
+++ v6
@@ -76,3 +76,34 @@

 **`./project_make`**

+##### Supplying your own function. #####
+
+It is possible to supply your own function to be applied in the calculation of the many equilibria.  The simplest way to do this is to write your own *many_eq_user_function.cpp* and *many_eq_user_function.h* based on the examples in the directory *my_user_extra*.  Those examples compute the rate of change of Y_e as computed from approximate weak rates presented by [Arcones et al](http://adsabs.harvard.edu/abs/2010A%26A...522A..25A).
+
+First, make sure that you have created a *my_user* directory.  This is done automatically in the steps above, so you might just want to type
+
+**`./project_make`**
+
+Then copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* into *my_user*.  For example, you can type, in the *many_equilibria* directory,
+
+**`cp my_user_extra/many_eq_user_function.* ../nucnet-tools-code/my_user/`**
+
+Then set the environment variable MANY_EQ_FUNC to *mine*:
+
+**`export MANY_EQ_FUNC=mine`**
+
+Now make the codes:
+
+**`./project_make`**
+
+You can run the appropriate code (for the NSE conditions described above) by typing
+
+**`./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.5 -inf "[z <= 50]"`**
+
+The *-inf* is the electron neutrino chemical potential / kT.  The output columns are *T₉*, *ρ*, 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.
+
+To use your own function, copy your *many_eq_user_function.cpp* and *many_eq_user_function.h* to *my_user* and follow the above steps.  Do not type
+
+**`make cleanll_my_user`**
+
+unless you want to remove your functions.  The directory *nucnet-tools-code/my_user* is not version controlled by NucNet Tools, so you can version control its contents in your own repository, if you wish.

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 23 Nov 2013 16:03:41 -0000

--- v4
+++ v5
@@ -68,5 +68,11 @@

 The output columns are *T₉*, *ρ*, *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 or add equilibrium constraints as described above.
+You can also redirect output 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 cleanall_my_user`**
+
+**`./project_make`**
+

many_equilibria modified by Bradley S. Meyer

Bradley S. Meyer — Sat, 23 Nov 2013 15:07:04 -0000

--- v3
+++ v4
@@ -47,3 +47,26 @@
 **`./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.45 ca40 "" "[z > 2]" 0.02`**

 Notice in this case that I must include the XPath expression on the nuclei, which, in this case, I choose *""* to include all nuclei.  The constraint and the larger number of nuclei included in this calculation will make it run slower than the NSE calculation above.  If possible, you will probably want to limit the nuclei involved with a more restrictive XPath expression.
+
+##### 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](http://www.gnu.org/software/bash/manual/bashref.html), 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 cleanall_my_user`**
+
+Now you can remake the codes by typing
+
+**`./project_make`**
+
+Run the appropriate code for the NSE conditions above by typing
+
+**`./compute_many_equil ../nucnet-tools-code/data_pub/my_net.xml 5. 10. 1.e5 1.e10 0.5 "[z <= 50]"`**
+
+The output columns are *T₉*, *ρ*, *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 or add equilibrium constraints as described above.
+