Enhancement:

- Add option --timestep-multipliers to enable more granular, phase-dependent, timestep multipliers (see documentation for use)
- Added maximum allowed value for options  and

Author: jeffriley

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

@@ -343,6 +343,7 @@ Default = 0.0
 
 **--debug-classes** |br|
 Developer-defined debug classes to enable (vector). |br|
+See :doc:`Vector program options <./program-options-vector-options>` for option format. |br|
 Default = `All debug classes enabled (e.g. no filtering)`
 
 **--debug-level** |br|
@@ -694,6 +695,7 @@ Default = HURLEY_ADD |br|
 
 **--log-classes** |br|
 Logging classes to be enabled (vector). |br|
+See :doc:`Vector program options <./program-options-vector-options>` for option format. |br|
 Default = `All debug classes enabled (e.g. no filtering)`
 
 **--logfile-common-envelopes** |br|
@@ -992,11 +994,13 @@ Default = SSE
 
 **--notes** |br|
 Annotation strings (vector). |br|
-Default = ""
+See :doc:`Vector program options <./program-options-vector-options>` for option format. |br|
+Default = "" for each annotation
 
 **--notes-hdrs** |br|
 Annotations header strings (vector). |br|
-Default = `No annotations`
+See :doc:`Vector program options <./program-options-vector-options>` for option format. |br|
+Default = `No annotation headers (no annotations)`
 
 **--number-of-systems [ -n ]** |br|
 The number of systems to simulate. |br|
@@ -1334,10 +1338,29 @@ User-defined timesteps filename. (See :doc:`Timestep files <../timestep-files>`)
 Default = ’’ (None)
 
 **--timestep-multiplier** |br|
-Multiplicative factor for timestep duration.  This multiplier is applied after the timesteps are chosen using other program options 
-such as ``--radial-change-fraction`` and ``--mass-change-fraction``, and will therefore override expected behaviour.  This option is 
-primarily intended for debugging/testing of convergence issues rather than for production runs. |br|
- Default = 1.0
+Multiplicative factor for timestep duration.  |br|
+|br|
+This multiplier is applied after the timesteps are chosen using other program options such as ``--radial-change-fraction`` 
+and ``--mass-change-fraction``, and will therefore override expected behaviour.  |br|
+This option can be used in conjunction with ``--timestep-multipliers``, in which case this multiplier, and the appropriate
+phase-dependent multiplier (specified by ``--timestep-multipliers``) are both applied. |br|
+Default = 1.0 |br| |br|
+This option is primarily intended for debugging/testing of convergence issues rather than for production runs. |br|
+
+**--timestep-multipliers** |br|
+Phase-dependent multiplicative factors for timestep duration. |br|
+See :doc:`Vector program options <./program-options-vector-options>` for option format. |br|
+A multicative factor can be specified for each phase (stellar type), where the ordinal value (zero-based) of the option value
+indicates the stellar type (from ``MS_LTE_07`` to ``CHEMICALLY_HOMOGENEOUS``, see stellar type list at 
+:doc:`../../Developer guide/Headers/typedefs-dot-h`>). |br|
+|br|
+This multiplier is applied after the timesteps are chosen using other program options such as ``--radial-change-fraction`` and 
+``--mass-change-fraction``, and will therefore override expected behaviour. |br|
+This option can be used in conjunction with ``--timestep-multiplier``, in which case that multiplier, and the appropriate
+phase-dependent multiplier (specified by ``--timestep-multipliers``) are both applied. |br|
+Default = 1.0 for each phase (stellar type) |br| |br|
+This option is primarily intended for debugging/testing of convergence issues rather than for production runs. |br|
+
 
 .. _options-props-U:
 

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

@@ -12,6 +12,7 @@ Currently, the only vector program options are:
 - --log-classes
 - --notes-hdrs
 - --notes
+- --timestep-multipliers
 
 
 The notation for vector program options provides for the specification of one or more values. e.g.::
@@ -26,8 +27,8 @@ for program options (to the command-line value, then to the COMPAS default) - le
 `log-class` had been left blank), and specifying an empty string ("") for a value would be ambiguous (as to whether the user wanted the
 option value to default, or just be an empty string).
 
-Non-numeric option values (in general, but also specifically for vector options) may not begin with the dash character ('-'), because the
-shell parser will parse them as option names before passing them through to COMPAS.
+Option values beyond the first value may not begin with the dash character ('-'), because the shell parser will parse them as option names
+before passing them through to COMPAS (this is a Boost limitation).
 
 COMPAS imposes no limit to the length (number of characters) of an individual option values that are specified as strings, but there may 
 be practical limits imposed by the underlying system.

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

@@ -51,7 +51,7 @@ Both option ``--grid-start-line`` and ``--grid-lines-to-process`` are ignored if
 Example
 ~~~~~~~
 
-We will submit a set of COMPAS runs using a grid-file ``grid_demo.txt''
+We will submit a set of COMPAS runs using a grid-file ``grid_demo.txt``
 .. code-block::
 
     COMPAS --grid grid_demo.txt

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

@@ -140,7 +140,7 @@ Bonus Info
 ----------
 
 Dockerfile
-^^^^^^^^^^
+~~~~~~~~~~
 
 The `Dockerfile <https://docs.docker.com/engine/reference/builder/>`__ defines how the docker image is constructed.
 
@@ -159,7 +159,7 @@ The Dockerfile for COMPAS consists of 8 layers:
 Dockerfiles usually end with a `CMD` directive specifying the command to run when the container starts. COMPAS does not have a `CMD` directive because some users will run the executable directly, while others will use `runSubmit.py`.
 
 Makefile.docker
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 A separate makefile is required for Docker to:
     1. Separate compiled files from source files.

online-docs/pages/whats-new.rst

@@ -3,10 +3,15 @@ What's new
 
 Following is a brief list of important updates to the COMPAS code.  A complete record of changes can be found in the file ``changelog.h``.
 
+**03.18.00 Apr 13, 2025**
+
+New command line option:
+
+* ``--timestep-multipliers`` to enable more granular, phase-dependent, timestep multipliers
+
 **03.17.00 Mar 22, 2025**
 
-* Added ENVELOPE_STATE_PRESCRIPTION::CONVECTIVE_MASS_FRACTION (default threshold of convective envelope by mass to label envelope 
-convective is 0.1, can be set with --convective-envelope-mass-threshold)
+* Added ENVELOPE_STATE_PRESCRIPTION::CONVECTIVE_MASS_FRACTION (default threshold of convective envelope by mass to label envelope convective is 0.1, can be set with --convective-envelope-mass-threshold)
 * Stable mass transfer now conserves angular momentum after accounting for the rotational angular momentum lost or gained by the stars
 * Imposed Keplerian rotation limit on mass-gaining stars:
 * Response depends on the new --response-to-spin-up option

src/BaseBinaryStar.cpp

@@ -2953,12 +2953,14 @@ void BaseBinaryStar::EmitGravitationalWave(const double p_Dt) {
  *
  * double ChooseTimestep(const double p_Multiplier)
  * 
- * @param   [IN]    p_Multiplier                timestep multiplier
+ * @param   [IN]    p_Factor                    factor applied to timestep (in addition to multipliers)
  * @return                                      new timestep in Myr
  */
-double BaseBinaryStar::ChooseTimestep(const double p_Multiplier) {
+double BaseBinaryStar::ChooseTimestep(const double p_Factor) {
 
-    double dt = std::min(m_Star1->CalculateTimestep(), m_Star2->CalculateTimestep());       // dt = smaller of timesteps required by individual stars
+    double dt1 = m_Star1->CalculateTimestep();
+    double dt2 = m_Star2->CalculateTimestep();
+    double dt  = std::min(dt1, dt2);                                                        // dt = smaller of timesteps required by individual stars
 
     if (!IsUnbound()) {                                                                     // check that binary is bound
 
@@ -3007,7 +3009,8 @@ double BaseBinaryStar::ChooseTimestep(const double p_Multiplier) {
         }
     }
 
-    dt *= p_Multiplier;	
+    // apply timestep multipliers
+    dt *= OPTIONS->TimestepMultiplier() * (dt1 < dt2 ? OPTIONS->TimestepMultipliers(static_cast<int>(m_Star1->StellarType())) : OPTIONS->TimestepMultipliers(static_cast<int>(m_Star2->StellarType()))) * p_Factor;
 
     return std::max(std::round(dt / TIMESTEP_QUANTUM) * TIMESTEP_QUANTUM, TIDES_MINIMUM_FRACTIONAL_NUCLEAR_TIME * NUCLEAR_MINIMUM_TIMESTEP); // quantised and not less than minimum
 }
@@ -3240,7 +3243,7 @@ EVOLUTION_STATUS BaseBinaryStar::Evolve() {
                 }
 
                 // we want the first timestep to be small - calculate timestep and divide by 1000.0
-                dt = ChooseTimestep(OPTIONS->TimestepMultiplier() / 1000.0);                                                            // calculate timestep - make first step small
+                dt = ChooseTimestep(0.001);                                                                                             // calculate timestep - make first step small
             }
 
             unsigned long int stepNum = 1; 
@@ -3370,7 +3373,7 @@ EVOLUTION_STATUS BaseBinaryStar::Evolve() {
                             dt = timesteps[stepNum];
                         }
                         else {                                                                                                          // no - not using user-provided timesteps
-                            dt = ChooseTimestep(OPTIONS->TimestepMultiplier());
+                            dt = ChooseTimestep();
                         }
 
                         stepNum++;                                                                                                      // increment stepNum

src/BaseBinaryStar.h

@@ -418,7 +418,7 @@ class BaseBinaryStar {
     void    CalculateGravitationalRadiation();
     void    EmitGravitationalWave(const double p_Dt);
 
-    double  ChooseTimestep(const double p_Multiplier);
+    double  ChooseTimestep(const double p_Factor = 1.0);
 
     void    CalculateEnergyAndAngularMomentum();
 

src/Options.h

@@ -274,7 +274,6 @@ class Options {
         ~ShorthandDefault_t() {}
     };
 
-
     typedef std::tuple<std::string, bool, TYPENAME, ShorthandDefault_t> SHORTHAND_ENTRY;                                        // option name, default allowed (i.e. can be omitted), default string
 
     std::vector<SHORTHAND_ENTRY> m_ShorthandAllowed = {

src/Star.cpp

@@ -449,7 +449,7 @@ EVOLUTION_STATUS Star::Evolve(const long int p_Id) {
                     dt = timesteps[stepNum];
                 }
                 else {                                                                                          // not using user-provided timesteps
-                    dt = m_Star->CalculateTimestep() * OPTIONS->TimestepMultiplier();                           // calculate new timestep   
+                    dt = m_Star->CalculateTimestep() * OPTIONS->TimestepMultiplier() * OPTIONS->TimestepMultipliers(static_cast<int>(m_Star->StellarType())); // calculate new timestep   
                     dt = std::round(dt / TIMESTEP_QUANTUM) * TIMESTEP_QUANTUM;                                  // quantised
                 }
                 stepNum++;                                                                                      // increment step number                                                      

src/changelog.h

@@ -1526,9 +1526,10 @@
 //  03.17.02    JR - Apr 11, 2025   - Defect Repair:
 //                                      - Remove extraneous debug print statement in MainSequence.h (inavertently added by me in v03.17.00)
 //                                      - fix description of return value for BaseStar::CalculateOmegaCHE()
-//  03.17.03    JR - Apr 12, 2025   - Enhancement:
-//                                      - Add option "--timestep-multipliers" to enable more granular, phase-dependent, timestep multipliers
+//  03.18.00    JR - Apr 13, 2025   - Enhancement:
+//                                      - Add option "--timestep-multipliers" to enable more granular, phase-dependent, timestep multipliers (see documentation for use)
+//                                      - Added maximum allowed value for options `--timestep-multiplier` and `--timestep-multipliers`
 
-const std::string VERSION_STRING = "03.17.03";
+const std::string VERSION_STRING = "03.18.00";
 
 # endif // __changelog_h__