Running COMPAS using a grid file

A grid file allows users to specify initial values for multiple systems for both Single Star Evolution (SSE) and Binary Star Evolution (BSE). Each line of a grid file is used by COMPAS to set the initial conditions and evolutionary parameters for an individual single star (SSE) or binary star (BSE), and each single star or binary star defined by a grid file line is evolved using those values.

Each line of a grid file is a set of program option specifications, with the specifications being exactly as they would appear on the command line if running COMPAS from the command line.

For example, a grid file could contain the following two lines:

--metallicity 0.001 --eccentricity 0.0 --remnant-mass-prescription fryer2012
--remnant-mass-prescription mullermandel --metallicity 0.02 --semi-major-axis 45.678

in which case COMPAS would evolve two binaries, with the option values set per the grid file lines.

Grid 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.

Not all program options can be specified in a grid file. Options that should remain constant for a single execution of COMPAS, such as options that specify the mode of evolution (e.g. --mode), or the name or path of output files (e.g. --output-path, --logfile-detailed-output etc.) can only be specified on the command line. COMPAS will issue an error message if an option that is not supported in a grid file is specified on a grid file line.

COMPAS imposes no limit on the number of grid file lines: the size of a grid file is limited only by the filesystem of the host system.

Specifying a Subset of the Grid File to be Processed

Users can instruct COMPAS to process only a subset of a specified grid file. This is achieved via the program options --grid-start-line, and --grid-lines-to-process:

The --grid-start-line program option takes a single parameter: an integer specifying the zero-based line number of the first line of the grid file to be processed. The default value is 0 - the first line of the grid file. Specifying a start line beyond the end of the grid file will result in an UNEXPECTED-END-OF-FILE error.

The --grid-lines-to-process program option takes a single parameter: an integer specifying the number of lines of the grid file to be processed. The default is to process all lines in the grid file from the start line (which may have been specified by the --grid-start-line option) through to the end of the grid file. Specifying a number of lines to be processed that, when coupled with the start line, would result in attempting to process lines beyond the end of the grid file will result in an INCOMPLETE-GRID error.

Note that blank lines and comments count towards the number of grid lines processed by COMPAS when deciding if the number specified by the user has been reached.

Both option --grid-start-line and --grid-lines-to-process are ignored if no grid file is specified via the --grid program option.

Example

We will submit a set of COMPAS runs using a grid-file ``grid_demo.txt'' .. code-block:

COMPAS --grid grid_demo.txt

Contents of grid_demo.txt:

.. include:: example/grid_demo.txt

Output:

COMPAS v02.38.04 Compact Object Mergers: Population Astrophysics and Statistics by Team COMPAS (http://compas.science/index.html) A binary star simulator

Start generating binaries at Thu Sep 5 14:51:57 2024

Generated 4 of 4 binaries requested

End generating binaries at Thu Sep 5 14:51:58 2024

Clock time = 0.175891 CPU seconds Wall time = 0000:00:00 (hhhh:mm:ss)

COMMAND LINE OPTIONS

PISN-lower-limit = 60.000000, DEFAULT_USED, DOUBLE PISN-upper-limit = 135.000000, DEFAULT_USED, DOUBLE PPI-lower-limit = 35.000000, DEFAULT_USED, DOUBLE PPI-upper-limit = 60.000000, DEFAULT_USED, DOUBLE YAML-template = '', DEFAULT_USED, STRING add-options-to-sysparms = 'GRID', DEFAULT_USED, STRING allow-non-stripped-ECSN = FALSE, DEFAULT_USED, BOOL allow-rlof-at-birth = TRUE, DEFAULT_USED, BOOL allow-touching-at-birth = FALSE, DEFAULT_USED, BOOL angular-momentum-conservation-during-circularisation = FALSE, DEFAULT_USED, BOOL black-hole-kicks = 'FALLBACK', DEFAULT_USED, STRING case-BB-stability-prescription = 'ALWAYS_STABLE', DEFAULT_USED, STRING check-photon-tiring-limit = FALSE, DEFAULT_USED, BOOL chemically-homogeneous-evolution = 'PESSIMISTIC', DEFAULT_USED, STRING circularise-binary-during-mass-transfer = TRUE, DEFAULT_USED, BOOL common-envelope-allow-immediate-RLOF-post-CE-survive = FALSE, DEFAULT_USED, BOOL common-envelope-allow-main-sequence-survive = TRUE, DEFAULT_USED, BOOL common-envelope-allow-radiative-envelope-survive = FALSE, DEFAULT_USED, BOOL common-envelope-alpha = 1.000000, DEFAULT_USED, DOUBLE common-envelope-alpha-thermal = 1.000000, DEFAULT_USED, DOUBLE common-envelope-formalism = 'ENERGY', DEFAULT_USED, STRING common-envelope-lambda = 0.100000, DEFAULT_USED, DOUBLE common-envelope-lambda-multiplier = 1.000000, DEFAULT_USED, DOUBLE common-envelope-lambda-nanjing-enhanced = FALSE, DEFAULT_USED, BOOL common-envelope-lambda-nanjing-interpolate-in-mass = FALSE, DEFAULT_USED, BOOL common-envelope-lambda-nanjing-interpolate-in-metallicity = FALSE, DEFAULT_USED, BOOL common-envelope-lambda-nanjing-use-rejuvenated-mass = FALSE, DEFAULT_USED, BOOL common-envelope-lambda-prescription = 'LAMBDA_NANJING', DEFAULT_USED, STRING common-envelope-mass-accretion-constant = 0.000000, DEFAULT_USED, DOUBLE common-envelope-mass-accretion-max = 0.100000, DEFAULT_USED, DOUBLE common-envelope-mass-accretion-min = 0.040000, DEFAULT_USED, DOUBLE common-envelope-mass-accretion-prescription = 'ZERO', DEFAULT_USED, STRING common-envelope-recombination-energy-density = 15000000000000.000000, DEFAULT_USED, DOUBLE common-envelope-slope-kruckow = -0.833333, DEFAULT_USED, DOUBLE convective-envelope-temperature-threshold = 5370.000000, DEFAULT_USED, DOUBLE cool-wind-mass-loss-multiplier = 1.000000, DEFAULT_USED, DOUBLE create-YAML-file = '', DEFAULT_USED, STRING critical-mass-ratio-HG-degenerate-accretor = 0.210000, DEFAULT_USED, DOUBLE critical-mass-ratio-HG-non-degenerate-accretor = 0.250000, DEFAULT_USED, DOUBLE critical-mass-ratio-MS-high-mass-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE critical-mass-ratio-MS-high-mass-non-degenerate-accretor = 0.625000, DEFAULT_USED, DOUBLE critical-mass-ratio-MS-low-mass-degenerate-accretor = 1.000000, DEFAULT_USED, DOUBLE critical-mass-ratio-MS-low-mass-non-degenerate-accretor = 1.440000, DEFAULT_USED, DOUBLE critical-mass-ratio-giant-degenerate-accretor = 0.870000, DEFAULT_USED, DOUBLE critical-mass-ratio-giant-non-degenerate-accretor = -1.000000, DEFAULT_USED, DOUBLE critical-mass-ratio-helium-HG-degenerate-accretor = 0.210000, DEFAULT_USED, DOUBLE critical-mass-ratio-helium-HG-non-degenerate-accretor = 0.250000, DEFAULT_USED, DOUBLE critical-mass-ratio-helium-MS-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE critical-mass-ratio-helium-MS-non-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE critical-mass-ratio-helium-giant-degenerate-accretor = 0.870000, DEFAULT_USED, DOUBLE critical-mass-ratio-helium-giant-non-degenerate-accretor = 1.280000, DEFAULT_USED, DOUBLE critical-mass-ratio-prescription = 'NONE', DEFAULT_USED, STRING critical-mass-ratio-white-dwarf-degenerate-accretor = 1.600000, DEFAULT_USED, DOUBLE critical-mass-ratio-white-dwarf-non-degenerate-accretor = 0.000000, DEFAULT_USED, DOUBLE debug-classes = { }, DEFAULT_USED, VECTOR<STRING> debug-level = 0, DEFAULT_USED, SIGNED debug-to-file = FALSE, DEFAULT_USED, BOOL detailed-output = FALSE, DEFAULT_USED, BOOL eccentricity = 0.000000, DEFAULT_USED, DOUBLE eccentricity-distribution = 'ZERO', DEFAULT_USED, STRING eccentricity-max = 1.000000, DEFAULT_USED, DOUBLE eccentricity-min = 0.000000, DEFAULT_USED, DOUBLE eddington-accretion-factor = 1.000000, DEFAULT_USED, DOUBLE enable-warnings = FALSE, DEFAULT_USED, BOOL envelope-state-prescription = 'LEGACY', DEFAULT_USED, STRING errors-to-file = FALSE, DEFAULT_USED, BOOL evolve-pulsars = FALSE, DEFAULT_USED, BOOL evolve-unbound-systems = TRUE, DEFAULT_USED, BOOL expel-convective-envelope-above-luminosity-threshold = FALSE, DEFAULT_USED, BOOL fix-dimensionless-kick-magnitude = -1.000000, DEFAULT_USED, DOUBLE fryer-22-fmix = 0.500000, DEFAULT_USED, DOUBLE fryer-22-mcrit = 5.750000, DEFAULT_USED, DOUBLE fryer-supernova-engine = 'DELAYED', DEFAULT_USED, STRING grid = 'grid_demo.txt', USER_SUPPLIED, STRING grid-lines-to-process = 9223372036854775807, DEFAULT_USED, LONG grid-start-line = 0, DEFAULT_USED, LONG hdf5-buffer-size = 1, DEFAULT_USED, SIGNED hdf5-chunk-size = 100000, DEFAULT_USED, SIGNED help = FALSE, DEFAULT_USED, BOOL hmxr-binaries = FALSE, DEFAULT_USED, BOOL initial-mass = 5.000000, DEFAULT_USED, DOUBLE initial-mass-1 = 5.000000, DEFAULT_USED, DOUBLE initial-mass-2 = 5.000000, DEFAULT_USED, DOUBLE initial-mass-function = 'KROUPA', DEFAULT_USED, STRING initial-mass-max = 150.000000, DEFAULT_USED, DOUBLE initial-mass-min = 5.000000, DEFAULT_USED, DOUBLE initial-mass-power = 0.000000, DEFAULT_USED, DOUBLE kick-direction = 'ISOTROPIC', DEFAULT_USED, STRING kick-direction-power = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude-1 = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude-2 = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude-distribution = 'MULLERMANDEL', DEFAULT_USED, STRING kick-magnitude-max = -1.000000, DEFAULT_USED, DOUBLE kick-magnitude-random = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude-random-1 = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude-random-2 = 0.000000, DEFAULT_USED, DOUBLE kick-magnitude-sigma-CCSN-BH = 265.000000, DEFAULT_USED, DOUBLE kick-magnitude-sigma-CCSN-NS = 265.000000, DEFAULT_USED, DOUBLE kick-magnitude-sigma-ECSN = 30.000000, DEFAULT_USED, DOUBLE kick-magnitude-sigma-USSN = 30.000000, DEFAULT_USED, DOUBLE kick-mean-anomaly-1 = 0.000000, DEFAULT_USED, DOUBLE kick-mean-anomaly-2 = 0.000000, DEFAULT_USED, DOUBLE kick-phi-1 = 0.000000, DEFAULT_USED, DOUBLE kick-phi-2 = 0.000000, DEFAULT_USED, DOUBLE kick-scaling-factor = 1.000000, DEFAULT_USED, DOUBLE kick-theta-1 = 0.000000, DEFAULT_USED, DOUBLE kick-theta-2 = 0.000000, DEFAULT_USED, DOUBLE log-classes = { }, DEFAULT_USED, VECTOR<STRING> log-level = 0, DEFAULT_USED, SIGNED logfile-common-envelopes = 'BSE_Common_Envelopes', DEFAULT_USED, STRING logfile-common-envelopes-record-types = -1, DEFAULT_USED, SIGNED logfile-definitions = '', DEFAULT_USED, STRING logfile-detailed-output = 'BSE_Detailed_Output', DEFAULT_USED, STRING logfile-detailed-output-record-types = -1, DEFAULT_USED, SIGNED logfile-double-compact-objects = 'BSE_Double_Compact_Objects', DEFAULT_USED, STRING logfile-double-compact-objects-record-types = -1, DEFAULT_USED, SIGNED logfile-name-prefix = '', DEFAULT_USED, STRING logfile-pulsar-evolution = 'BSE_Pulsar_Evolution', DEFAULT_USED, STRING logfile-pulsar-evolution-record-types = -1, DEFAULT_USED, SIGNED logfile-rlof-parameters = 'BSE_RLOF', DEFAULT_USED, STRING logfile-rlof-parameters-record-types = -1, DEFAULT_USED, SIGNED logfile-supernovae = 'BSE_Supernovae', DEFAULT_USED, STRING logfile-supernovae-record-types = -1, DEFAULT_USED, SIGNED logfile-switch-log = 'BSE_Switch_Log', DEFAULT_USED, STRING logfile-system-parameters = 'BSE_System_Parameters', DEFAULT_USED, STRING logfile-system-parameters-record-types = -1, DEFAULT_USED, SIGNED logfile-type = 'HDF5', DEFAULT_USED, STRING luminosity-to-mass-threshold = 4.200000, DEFAULT_USED, DOUBLE luminous-blue-variable-multiplier = 1.500000, DEFAULT_USED, DOUBLE luminous-blue-variable-prescription = 'HURLEY_ADD', DEFAULT_USED, STRING mass-loss-prescription = 'VINK', DEFAULT_USED, STRING mass-ratio = 1.000000, DEFAULT_USED, DOUBLE mass-ratio-distribution = 'FLAT', DEFAULT_USED, STRING mass-ratio-max = 1.000000, DEFAULT_USED, DOUBLE mass-ratio-min = 0.010000, DEFAULT_USED, DOUBLE mass-transfer = TRUE, DEFAULT_USED, BOOL mass-transfer-accretion-efficiency-prescription = 'THERMAL', DEFAULT_USED, STRING mass-transfer-angular-momentum-loss-prescription = 'ISOTROPIC', DEFAULT_USED, STRING mass-transfer-fa = 0.500000, DEFAULT_USED, DOUBLE mass-transfer-jloss = 1.000000, DEFAULT_USED, DOUBLE mass-transfer-jloss-macleod-linear-fraction = 0.500000, DEFAULT_USED, DOUBLE mass-transfer-rejuvenation-prescription = 'STARTRACK', DEFAULT_USED, STRING mass-transfer-thermal-limit-C = 10.000000, DEFAULT_USED, DOUBLE mass-transfer-thermal-limit-accretor = 'CFACTOR', DEFAULT_USED, STRING maximum-evolution-time = 13700.000000, DEFAULT_USED, DOUBLE maximum-mass-donor-nandez-ivanova = 2.000000, DEFAULT_USED, DOUBLE maximum-neutron-star-mass = 2.500000, DEFAULT_USED, DOUBLE maximum-number-timestep-iterations = 99999, DEFAULT_USED, SIGNED mcbur1 = 1.600000, DEFAULT_USED, DOUBLE metallicity = 0.014200, DEFAULT_USED, DOUBLE metallicity-distribution = 'ZSOLAR', DEFAULT_USED, STRING metallicity-max = 0.030000, DEFAULT_USED, DOUBLE metallicity-min = 0.000100, DEFAULT_USED, DOUBLE minimum-secondary-mass = 0.100000, DEFAULT_USED, DOUBLE mode = 'BSE', DEFAULT_USED, STRING muller-mandel-kick-multiplier-BH = 200.000000, DEFAULT_USED, DOUBLE muller-mandel-kick-multiplier-NS = 520.000000, DEFAULT_USED, DOUBLE muller-mandel-sigma-kick = 0.300000, DEFAULT_USED, DOUBLE neutrino-mass-loss-BH-formation = 'FIXED_MASS', DEFAULT_USED, STRING neutrino-mass-loss-BH-formation-value = 0.100000, DEFAULT_USED, DOUBLE neutron-star-equation-of-state = 'SSE', DEFAULT_USED, STRING notes = { }, DEFAULT_USED, VECTOR<STRING> notes-hdrs = { }, DEFAULT_USED, VECTOR<STRING> number-of-systems = 10, DEFAULT_USED, SIGNED orbital-period = 0.100000, DEFAULT_USED, DOUBLE orbital-period-distribution = 'FLATINLOG', DEFAULT_USED, STRING orbital-period-max = 1000.000000, DEFAULT_USED, DOUBLE orbital-period-min = 1.100000, DEFAULT_USED, DOUBLE output-container = 'COMPAS_Output', DEFAULT_USED, STRING output-path = '.', DEFAULT_USED, STRING overall-wind-mass-loss-multiplier = 1.000000, DEFAULT_USED, DOUBLE pair-instability-supernovae = TRUE, DEFAULT_USED, BOOL population-data-printing = FALSE, DEFAULT_USED, BOOL print-bool-as-string = FALSE, DEFAULT_USED, BOOL pulsar-birth-magnetic-field-distribution = 'ZERO', DEFAULT_USED, STRING pulsar-birth-magnetic-field-distribution-max = 13.000000, DEFAULT_USED, DOUBLE pulsar-birth-magnetic-field-distribution-min = 11.000000, DEFAULT_USED, DOUBLE pulsar-birth-spin-period-distribution = 'ZERO', DEFAULT_USED, STRING pulsar-birth-spin-period-distribution-max = 100.000000, DEFAULT_USED, DOUBLE pulsar-birth-spin-period-distribution-min = 10.000000, DEFAULT_USED, DOUBLE pulsar-magnetic-field-decay-massscale = 0.025000, DEFAULT_USED, DOUBLE pulsar-magnetic-field-decay-timescale = 1000.000000, DEFAULT_USED, DOUBLE pulsar-minimum-magnetic-field = 8.000000, DEFAULT_USED, DOUBLE pulsational-pair-instability = TRUE, DEFAULT_USED, BOOL pulsational-pair-instability-prescription = 'MARCHANT', DEFAULT_USED, STRING quiet = FALSE, DEFAULT_USED, BOOL random-seed = 0, DEFAULT_USED, UNSIGNED_LONG remnant-mass-prescription = 'MULLERMANDEL', DEFAULT_USED, STRING retain-core-mass-during-caseA-mass-transfer = TRUE, DEFAULT_USED, BOOL revised-energy-formalism-nandez-ivanova = FALSE, DEFAULT_USED, BOOL rlof-printing = TRUE, DEFAULT_USED, BOOL rotational-frequency = 0.000000, DEFAULT_USED, DOUBLE rotational-frequency-1 = 0.000000, DEFAULT_USED, DOUBLE rotational-frequency-2 = 0.000000, DEFAULT_USED, DOUBLE rotational-velocity-distribution = 'ZERO', DEFAULT_USED, STRING semi-major-axis = 0.100000, DEFAULT_USED, DOUBLE semi-major-axis-distribution = 'FLATINLOG', DEFAULT_USED, STRING semi-major-axis-max = 1000.000000, DEFAULT_USED, DOUBLE semi-major-axis-min = 0.010000, DEFAULT_USED, DOUBLE stellar-zeta-prescription = 'SOBERMAN', DEFAULT_USED, STRING store-input-files = TRUE, DEFAULT_USED, BOOL switch-log = FALSE, DEFAULT_USED, BOOL timestep-multiplier = 1.000000, DEFAULT_USED, DOUBLE use-mass-loss = TRUE, DEFAULT_USED, BOOL version = FALSE, DEFAULT_USED, BOOL wolf-rayet-multiplier = 0.100000, DEFAULT_USED, DOUBLE zeta-adiabatic-arbitrary = 10000.000000, DEFAULT_USED, DOUBLE zeta-main-sequence = 2.000000, DEFAULT_USED, DOUBLE zeta-radiative-envelope-giant = 6.500000, DEFAULT_USED, DOUBLE

OTHER PARAMETERS

useFixedUK = FALSE, CALCULATED, BOOL actual-output-path = /Users/avaj0001/Documents/projects/compas_dev/COMPAS/online-docs/pages/User guide/Running COMPAS/example, CALCULATED, STRING fixedRandomSeed = FALSE, CALCULATED, BOOL Actual random seed = 1725504717, CALCULATED, UNSIGNED_LONG