Merge branch 'dev' into postProcessingUpdates

Author: reinhold-willcox

online-docs/index.rst

@@ -11,6 +11,10 @@ COMPAS
 ======
 
 **C**\ ompact **O**\ bject **M**\ ergers: **P**\ opulation **A**\ strophysics and **S**\ tatistics
+is a publicly available rapid stellar / binary population synthesis code designed so that evolution prescriptions and model parameters are 
+easily adjustable. COMPAS draws properties for a binary star system from a set of initial distributions, and evolves it from 
+zero-age main sequence to the end of its life as two compact remnants. It has been used for inference from observations of 
+gravitational-wave mergers, Galactic neutron stars, X-ray binaries, and luminous red novae.
 
 `... by` `TeamCOMPAS <https://compas.science/index.html>`_
 

online-docs/pages/Getting started/building-COMPAS.rst

@@ -54,6 +54,11 @@ in which all source files are compiled, type::
 The `clean` option instructs ``make`` to remove all existing object files (.o), and the COMPAS executable.  A subsequent ``make`` is then forced to compile
 all source files and link the resultant object files (and external libraries) into a new executable.
 
+The executable can be tested with, e.g.,
+
+    ./COMPAS -v
+
+which will display the code version.
 
 See :doc:`../Developer guide/Developer build/COMPAS-local-build` for a detailed description of ``Makefile`` functionality.
 

online-docs/pages/User guide/Post-processing/post-processing-h5copy.rst

@@ -1,10 +1,10 @@
 h5copy.py
 =========
 
-This program copies ``HDF5`` file(s) to a designated output ``HDF5`` file. If the output file is an existing ``HDF5`` file,
-the user can  specify whether the existing content should be erased before copying begins, or whether the copied data should
-be appended to the existing data. If multiple files are given as input files, the resultant ``HDF5`` file is the concatenation
-of the input files.
+This program copies ``COMPAS_Output.h5`` ``HDF5`` file(s) [but not ``Detailed_Ouput`` files] to a designated output ``HDF5`` file. 
+If the output file is an existing ``HDF5`` file, the user can specify whether the existing content should be erased before copying 
+begins, or whether the copied data should be appended to the existing data. If multiple files are given as input files, the 
+resultant ``HDF5`` file is the concatenation of the input files.
 
 
 Some nomenclature

online-docs/pages/User guide/Program options/program-options-ranges.rst

@@ -32,6 +32,10 @@ where `range-specifier` is defined as:
         `start` and `increment` must be the same data type as option-name. |br|
         `count` must be a positive integer value.
 
+There should be no spaces inside the brackets ([]). Spaces on the command line are interpreted as argument delimiters
+by the shell parser before passing the command-line arguments to the COMPAS executable, so if spaces are present inside
+the brackets the shell parser breaks the range specification into multiple command-line arguments.
+
 To specify a range of values for the ``--metallicity`` option, a user, if running COMPAS from the command line
 and with no grid file, would type any of the following::
 
@@ -51,3 +55,9 @@ type::
     ./COMPAS --metallicity [0.0001,10,0.0013] --common-envelope-alpha [0.1,5,0.2]
 
 and COMPAS would evolve a grid of 50 binaries using the 10 metallicity values and 5 common envelope alpha values.
+
+Note that when a range is, or ranges are, specified on the command line, the ``--number-of-systems`` command-line option is ignored.
+This is to avoid multiple systems with identical initial values being evolved.  Ranges and sets can be mixed with grid files, and
+in that case ranges and sets specified on the command line will be played out for each grid file line.
+
+   

online-docs/pages/User guide/Program options/program-options-sets.rst

@@ -28,6 +28,10 @@ where `set-specifier` is defined as:
 
         `set-identifier` is mandatory for `set-specifier`. |br|
         `value`:sub:`i` must be the same data type as `option-name`.
+        
+There should be no spaces inside the brackets ([]). Spaces on the command line are interpreted as argument delimiters
+by the shell parser before passing the command-line arguments to the COMPAS executable, so if spaces are present inside
+the brackets the shell parser breaks the set specification into multiple command-line arguments.
 
 Valid values for boolean options are {1|0, TRUE|FALSE, YES|NO, ON|OFF}, and all set values must be of
 the same type (i.e. all 1|0, or all YES|NO etc.).
@@ -44,3 +48,9 @@ command line and with no grid file, would type any of the following::
 
 In each of the examples above the user has specified, by the use of the `set-specifier`, that three binary stars
 should be evolved, using the eccentricity distributions ’THERMALISED’, ’FIXED’, and ’FLAT’.
+
+Note that when a set is, or sets are, specified on the command line, the ``--number-of-systems`` command-line option is ignored.
+This is to avoid multiple systems with identical initial values being evolved.  Ranges and sets can be mixed with grid files, and
+in that case ranges and sets specified on the command line will be played out for each grid file line.
+
+   

online-docs/pages/User guide/Running COMPAS/running-via-docker-running.rst

@@ -13,9 +13,11 @@ To run COMPAS via a ``pythonSubmit.py`` file, type::
     docker run                                                  \
         --rm                                                    \
         -it                                                     \
+        -v $(pwd)/compas-input:/app/COMPAS/config               \
         -v $(pwd)/compas-logs:/app/COMPAS/logs                  \
         -v $(pwd)/pythonSubmit.py:/app/starts/pythonSubmit.py   \
         -e COMPAS_EXECUTABLE_PATH=/app/COMPAS/bin/COMPAS        \
+        -e COMPAS_INPUT_DIR_PATH=/app/COMPAS/config             \
         -e COMPAS_LOGS_OUTPUT_DIR_PATH=/app/COMPAS/logs         \
         teamcompas/compas                                       \
         python3 /app/starts/pythonSubmit.py                     
@@ -35,8 +37,9 @@ short for [-i and -t] - provides an interactive terminal\ [#f2]_.
 **-v <path-on-host>:<path-in-container>** |br|
 mount ``<path-on-host>`` to ``<path-in-container>``\ [#f3]_. |br|
 
-This time we not only want to get the output from COMPAS on the host machine, we also want to supply a ``pythonSubmit.py`` to the 
-container from the host machine.
+This time we not only want to read the COMPAS input files (i.e. grid file and/or logfile-definitions file) on the
+host from the container, and get the output from COMPAS in the container onto the host machine, we also want to 
+supply a ``pythonSubmit.py`` to the container from the host machine.
 
 **-e VAR_NAME=value** |br|
 set the environment variable ``VAR_VAME`` to `value`\ [#f4]_.
@@ -53,13 +56,14 @@ via the command line
 
 To run the COMPAS executable from the command line (i.e. without ``pythonSubmit.py``), type::
 
-    docker run                                  \
-        --rm                                    \
-        -it                                     \
-        -v $(pwd)/compas-logs:/app/COMPAS/logs  \
-        teamcompas/compas                       \
-        bin/COMPAS                              \
-        --number-of-systems=5                  \
+    docker run                                      \
+        --rm                                        \
+        -it                                         \
+        -v $(pwd)/compas-input:/app/COMPAS/config   \
+        -v $(pwd)/compas-logs:/app/COMPAS/logs      \
+        teamcompas/compas                           \
+        bin/COMPAS                                  \
+        --number-of-systems=5                       \
         --output-path=/app/COMPAS/logs
 
 
@@ -77,7 +81,9 @@ short for [-i and -t] - provides an interactive terminal\ [#f2]_.
 **-v <path-on-host>:<path-in-container>** |br|
 mount ``<path-on-host>`` to ``<path-in-container>``\ [#f3]_. |br|
 
-In this instance, make it so `$(pwd)/compas-logs` on my machine is the same as `/app/COMPAS/logs` inside the container.
+In this instance, make it so |br|
+   `$(pwd)/compas-input` on my machine is the same as `/app/COMPAS/config` inside the container. |br|
+   `$(pwd)/compas-logs` on my machine is the same as `/app/COMPAS/logs` inside the container.
 
 **teamcompas/compas** |br|
 the image to run.
@@ -102,7 +108,7 @@ environment, and are non-breaking changes (i.e. benign to other environments).
 ``COMPAS_EXECUTABLE_PATH`` specifies where ``pythonSubmit.py`` looks for the COMPAS executable. This override exists purely for 
 ease-of-use from the command line.
 
-`COMPAS_LOGS_OUTPUT_DIR_PATH` specifies where COMPAS output log filess are created. The override exists because the mounted directory 
+`COMPAS_LOGS_OUTPUT_DIR_PATH` specifies where COMPAS output log files are created. The override exists because the mounted directory 
 (option `-v`) is created before COMPAS runs. COMPAS sees that the directory where it's supposed to put logs already exists, so it 
 creates a different (i.e. non-mapped) directory for the output log files.
 
@@ -143,3 +149,4 @@ to get the container id of interest, then type::
 .. [#f5] https://docs.docker.com/engine/reference/run/
 .. [#f6] https://docs.docker.com/engine/reference/run/#detached--d
 
+   

src/BaseBinaryStar.cpp

@@ -2132,14 +2132,14 @@ void BaseBinaryStar::ResolveMassChanges() {
 
     // update mass of star1 according to mass loss and mass transfer, then update age accordingly
     (void)m_Star1->UpdateAttributes(m_Star1->MassPrev() - m_Star1->Mass() + m_Star1->MassLossDiff() + m_Star1->MassTransferDiff(), 0.0);    // update mass for star1
-    m_Star1->UpdateInitialMass();                                                                       // update initial mass of star1 (MS, HG & HeMS)  JR: todo: fix this kludge one day - mass0 is overloaded, and isn't always "initial mass"
+    m_Star1->UpdateInitialMass();                                                                       // update effective initial mass of star1 (MS, HG & HeMS)
     m_Star1->UpdateAgeAfterMassLoss();                                                                  // update age of star1
     m_Star1->ApplyMassTransferRejuvenationFactor();                                                     // apply age rejuvenation factor for star1
     m_Star1->UpdateAttributes(0.0, 0.0, true);
 
     // rinse and repeat for star2
     (void)m_Star2->UpdateAttributes(m_Star2->MassPrev() - m_Star2->Mass() + m_Star2->MassLossDiff() + m_Star2->MassTransferDiff(), 0.0);    // update mass for star2
-    m_Star2->UpdateInitialMass();                                                                       // update initial mass of star 2 (MS, HG & HeMS)  JR: todo: fix this kludge one day - mass0 is overloaded, and isn't always "initial mass"
+    m_Star2->UpdateInitialMass();                                                                       // update effective initial mass of star 2 (MS, HG & HeMS)
     m_Star2->UpdateAgeAfterMassLoss();                                                                  // update age of star2
     m_Star2->ApplyMassTransferRejuvenationFactor();                                                     // apply age rejuvenation factor for star2
     m_Star2->UpdateAttributes(0.0, 0.0, true);

src/BaseBinaryStar.h

@@ -543,7 +543,7 @@ class BaseBinaryStar {
             (void)donorCopy->UpdateAttributes(-dM, -dM*donorCopy->Mass0()/donorCopy->Mass());
 
             // Modify donor Mass0 and Age for MS (including HeMS) and HG stars
-            donorCopy->UpdateInitialMass();         // update initial mass (MS, HG & HeMS)  JR: todo: fix this kludge - mass0 is overloaded, and isn't always "initial mass"
+            donorCopy->UpdateInitialMass();         // update initial mass (MS, HG & HeMS)  
             donorCopy->UpdateAgeAfterMassLoss();    // update age (MS, HG & HeMS)
 
             (void)donorCopy->AgeOneTimestep(0.0);   // recalculate radius of star - don't age - just update values

src/BaseStar.cpp

@@ -1055,7 +1055,7 @@ double BaseStar::CalculateLogBindingEnergyLoveridge(bool p_IsMassLoss) const {
         logBindingEnergy += lCoefficients.alpha_mr * utils::intPow(log10(m_Mass), lCoefficients.m) * utils::intPow(log10(m_Radius + deltaR), lCoefficients.r);
     }
 
-    double MZAMS_Mass = (m_MZAMS - m_Mass) / m_MZAMS;
+    double MZAMS_Mass = (m_MZAMS - m_Mass) / m_MZAMS;                                       // Should m_ZAMS really be m_Mass0 (i.e., account for change in effective mass through mass loss in winds, MS mass transfer?)
     logBindingEnergy *= p_IsMassLoss ? 1.0 + (0.25 * MZAMS_Mass * MZAMS_Mass) : 1.0;        // apply mass-loss correction factor (lambda)
 
     constexpr double logBE0 = 33.29866;                                                     // JR: todo: what is this for?  Should it be in constants.h?
@@ -1239,7 +1239,7 @@ double BaseStar::CalculateLuminosityAtZAMS(const double p_MZAMS) {
  *
  * double CalculateLuminosityAtBAGB(double p_Mass)
  *
- * @param   [IN]    p_Mass                      Mass in Msol
+ * @param   [IN]    p_Mass                      (Effective) mass in Msol
  * @return                                      Luminosity at BAGB in Lsol
  */
 double BaseStar::CalculateLuminosityAtBAGB(double p_Mass) const {
@@ -1842,7 +1842,7 @@ void BaseStar::ResolveMassLoss() {
         m_COCoreMass=std::min(m_COCoreMass,m_Mass);                             // Not expected, only a precaution to avoid inconsistencies
         m_CoreMass=std::min(m_CoreMass, m_Mass);
 
-        UpdateInitialMass();                                                    // update initial mass (MS, HG & HeMS)  JR: todo: fix this kludge one day - mass0 is overloaded, and isn't always "initial mass"
+        UpdateInitialMass();                                                    // update effective initial mass (MS, HG & HeMS)
         UpdateAgeAfterMassLoss();                                               // update age (MS, HG & HeMS)
         ApplyMassTransferRejuvenationFactor();                                  // apply age rejuvenation factor
     }
@@ -2964,14 +2964,10 @@ void BaseStar::UpdateAttributesAndAgeOneTimestepPreamble(const double p_DeltaMas
  *      attributes are updated.  The p_DeltaMass parameter may be zero, in which case no change is made to the
  *      star's mass before the attributes of the star are calculated.
  *
- *    - if required, the star's initial mass is changed by the amount passed as the p_DeltaMass0 parameter before
- *      other attributes are updated.  The p_DeltaMass parameter may be zero, in which case no change is made to
- *      the star's mass before the attributes of the star are calculated.  This should be used infrequently, and
- *      is really a kludge because the Mass0 attribute in Hurley et al. 2000 was overloaded after the introduction
- *      of mass loss (see section 7.1).  We should really separate the different uses of Mass0 in the code and
- *      use a different variable - initial mass shouldn't change (other than to initial mass upon entering a
- *      stellar phase - it doesn't make a lot of sense for initial mass to change during evolution through the
- *      phase).         JR: todo: action this paragraph.
+ *    - if required, the star's effective initial mass is changed by the amount passed as the p_DeltaMass0 parameter before
+ *      other attributes are updated.  The p_DeltaMass0 parameter may be zero, in which case no change is made to
+ *      the star's mass before the attributes of the star are calculated.  The Mass0 attribute in Hurley et al. 2000 is overloaded by the introduction
+ *      of mass loss (see section 7.1).
  *
  *    - if required, the star is aged by the amount passed as the p_DeltaTime parameter, and the simulation time is
  *      advanced by the same amount, before other attributes are updated.  The p_deltaTime parameter may be zero,

src/BaseStar.h

@@ -201,8 +201,6 @@ class BaseStar {
 
     virtual void            ResolveMassLoss();
 
-    virtual STELLAR_TYPE    ResolveRemnantAfterEnvelopeLoss()                                                   { return m_StellarType; }
-
             void            SetStellarTypePrev(const STELLAR_TYPE p_StellarTypePrev)                            { m_StellarTypePrev = p_StellarTypePrev; }
 
             void            StashSupernovaDetails(const STELLAR_TYPE p_StellarType)                             { LOGGING->StashSSESupernovaDetails(this, p_StellarType); }