Update documention; allow comment lines in timesteps files

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

@@ -413,7 +413,7 @@ Default = 5.75
 :ref:`Back to Top <options-props-top>`
 
 **--grid** |br|
-Grid filename. |br|
+Grid filename. (See :doc:`Grid files <../grid-files>`) |br|
 Default = ’’ (None)
 
 **--grid-lines-to-process** |br|
@@ -1161,6 +1161,10 @@ Default = FALSE
 
 :ref:`Back to Top <options-props-top>`
 
+**--timestep-filename** |br|
+User-defined timesteps filename. (See :doc:`Timestep files <../timestep-files>`) |br|
+Default = ’’ (None)
+
 **--timestep-multiplier** |br|
 Multiplicative factor for timestep duration. |br|
 Default = 1.0

online-docs/pages/User guide/timestep-files.rst

@@ -0,0 +1,28 @@
+Timestep files
+==============
+
+A timestep file allows users to specify the timesteps to be taken during Single Star Evolution (SSE) or Binary Star Evolution (BSE).
+
+If a timestep file is provided (via the ``timesteps-filename`` program option), the COMPAS code uses the user-provided timeteps to
+evolve stars/systems instead of calculating a new timestep at each iteration. The COMPAS code will read the first non-blank and
+non-comment line of the timesteps file and set the first timestep to that value, then for each iteration during evolution, each
+subsequent non-blank and non-comment line of the timesteps file is read and the timestep for that iteration set to the value read.
+
+Note that COMPAS will use the timestep exactly as read - the timesteps read from the timesteps file are not quantised by COMPAS, and 
+neither will they be truncated to any limit (e.g. ``ABSOLUTE_MINIMUM_TIMESTEP`` from ``constants.h``) or multiplied by any timestep
+multiplier set by the ``timestep-multiplier`` option.  Furthermore, no check will be made after the timestep is taken to limit the
+radial expansion of the star being evolved.
+
+Timesteps files can have blank lines and comments. Comments begin with a hash/pound character ('#') - the hash/pound character and text 
+beyond it are ignored by COMPAS.
+
+The ``timesteps-filename`` option is valid both on the command line and in a grid file.  If the ``timesteps-filename`` option is specified
+in conjunction with the ``--number-of-systems`` (``-n``) option, or with option ranges and/or sets, the same timeteps file specified will
+be used for each star or system being evolved. On the other hand, if the ``timesteps-filename`` option is specified in a grid file, the
+timesteps file specified on a grid file line will be read and used for the star or system evolved by that grid file line.
+
+Each line of a timesteps file which is not a blank line or comment line must contain a single, non-negative, floating-point number (in
+plain text - COMPAS will read the plain text and convert it to a floating-point number).
+
+COMPAS imposes a hard limit of ``1,000,000`` timesteps in a timesteps file.
+

online-docs/pages/User guide/user-guide.rst

@@ -10,6 +10,7 @@ This section contains the basic user guide for COMPAS.
    ./configuration
    ./Program options/program-options
    ./grid-files
+   ./timestep-files
    ./random-seed
    ./Running COMPAS/running-compas
    ./COMPAS output/output

online-docs/pages/whats-new.rst

@@ -6,6 +6,12 @@ Following is a brief list of important updates to the COMPAS code.  A complete r
 
 **LATEST RELEASE** |br|
 
+**02.42.00 Jan 04, 2023**
+
+* Timesteps are now quantised to an integral multiple of 1e-12Myr.
+* New option provided to allow user-defined timesteps: ``--timesteps-filename`` (See :doc:`Timestep files <../"User guide"/timestep-files>`).
+* Code changes to make SSE and BSE evolution more consistent (See `PR 1052 <https://github.com/TeamCOMPAS/COMPAS/pull/1052>`_).
+
 **02.41.03 Dec 28, 2023**
 
 * The functions ``BaseBinaryStar::CalculateAngularMomentum()``, ``BaseBinaryStar::CalculateTotalEnergy()``, and ``BaseStar::AngularMomentum()`` changed to use moment of inertia instead of gyration radius.

src/changelog.h

@@ -1088,7 +1088,12 @@
 //                                      - Change to functionality (noted above) noted in 'What's New' online documentation page
 // 02.41.04     JR - Dec 30, 2023    - Defect repair:
 //                                      - Fix for issue #1048
-// 02.42.99     JR - Jan 04. 2024    - Enhancements etc. TBC
+// 02.42.99     JR - Jan 04. 2024    - Enhancements, defect repair, a little cleanup
+//                                      - added `timesteps-filename` option to allow users to provide preset timesteps for both SSE and BSE
+//                                      - updated documentation for new option; updated `What's New`
+//                                      - SSE vs BSE consistency: modified SSE to evolve a single star exactly as the primary in a wide binary with small companion
+//                                      - quantised timesteps to an integral multiple of 1E-12Myr - new constant `TIMESTEP_QUANTUM` in constants.h
+//                                      - little bit of code cleanup
 
 const std::string VERSION_STRING = "02.42.00";
 

src/utils.cpp

@@ -1492,7 +1492,9 @@ namespace utils {
                                 rec.erase(rec.size() - 1);                                                          // yes - strip it
                             }
 
-                            if (!rec.empty()) {                                                                     // blank record?                                 
+                            rec = trim(rec);                                                                        // remove leading and trailing blanks
+
+                            if (!rec.empty() or rec[0] == '#') {                                                    // blank record or comment?                                 
                                 try {                                                                               // no - process it
                                     size_t lastChar;
                                     long double v = std::stold(rec, &lastChar);                                     // try conversion
@@ -1501,7 +1503,13 @@ namespace utils {
                                         break;                                                                      // stop processing
                                     }
 
-                                    timesteps.push_back(v);                                                         // add timestep to timesteps vector
+                                    if (v < 0.0) {                                                                  // timestep must be >= 0.0
+                                       error = ERROR::INVALID_VALUE_IN_TIMESTEPS_FILE;                              // not a valid timestep
+                                       break;                                                                       // stop processing
+                                    }
+                                    else {                                                                          // ok - timestep >= 0.0
+                                        timesteps.push_back(v);                                                     // add timestep to timesteps vector
+                                    }
 
                                     numTimesteps++;                                                                 // increment number of timesteps read
                                     if (numTimesteps >= ABSOLUTE_MAXIMUM_TIMESTEPS) {                               // number of timesteps exceeds maximum?