Troubleshooting

This page collects fixes for problems users commonly run into, organized by where they show up: building SLUG, locating its data files, writing an input deck, setting up nucleosynthetic yields, running a simulation, and post-processing with Cloudy. If your problem isn’t covered here, the individual pages linked from each section below go into much more detail.

Building SLUG

SLUG requires a C++23-capable compiler with two specific features (multidimensional operator[] and std::views::zip) that not every nominally-C++23 compiler provides – see Dependencies for exactly which compiler/standard-library combinations are verified to work, and Configuring and Building for the -DSLUG_MDSPAN_PROVIDER option if the build fails specifically on <mdspan>. If cmake --build build doesn’t also build this documentation site, that’s expected unless Doxygen, Sphinx, Breathe, and Exhale are all installed – see Building this Documentation.

Data Files Not Found

SLUG’s own git repository does not include the large stellar track, atmosphere, and filter data files – these are downloaded separately (see Getting SLUG). If they haven’t been downloaded, or SLUG can’t find them, you’ll typically see an error like

findMatchingTracks: unable to open HDF5 file .../data/tracks/mist.h5

or

findMatchingTracks: no trackset named MIST

The first indicates the registry entry points to a file that isn’t actually there (usually because the data files were never downloaded); the second indicates the registry itself doesn’t know about the track set you asked for (a typo in stars.tracks, or a custom registry file that doesn’t list it). The same pattern applies to spectral synthesis models (findMatchingSpectra: ...).

Things to check, in order:

  1. Did you run python data/tools/download_data.py (see Getting SLUG)? Without it, data/tracks, data/spectra, etc. only contain registry files, not the HDF5 data they point to.

  2. Is the SLUG_DIR environment variable set to the repository root (see Running a SLUG Simulation)? File names in the input deck are resolved relative to the current working directory first, then SLUG_DIR, then the repository root determined at build time – if you run slug from some other directory with SLUG_DIR unset, and that directory doesn’t happen to contain its own copy of data/, resolution can fail even though the data files exist elsewhere on disk.

  3. If you’re using a custom registry file (see e.g. Standard Track Sets for the track-registry format), remember that each entry’s file key is resolved relative to the registry file’s own directory, not the current working directory – a registry moved without the data files it describes (or vice versa) will fail to resolve even though both files exist somewhere.

Input Deck Errors

SLUG validates the input deck up front, before running any simulation, and reports a specific missing or malformed keyword rather than a generic parse failure, e.g.:

SimControls: sim_type not found
SimControls: sim_type must be 'galaxy' or 'cluster'
SimControls: unknown output_mode <value>
SimControls: output.start_time not found

These all mean the same thing: a required keyword is missing, misspelled, or has an invalid value. See The SLUG Input Deck for the full, authoritative list of keywords, their exact spelling, and which section of the input deck each belongs in – a required keyword given at the wrong nesting level (e.g. outside its [section]) is reported the same way as if it were missing entirely, while an optional keyword given at the wrong level, or misspelled, is reported as an unused key (see below).

One combination is rejected outright rather than merely defaulting: requesting checkpointing (output.checkpoint_interval non-zero) together with output.output_mode = "ascii":

SimControls: output.checkpoint_interval is non-zero, but checkpointing
is only supported with HDF5 output (output.output_mode = "h5" or
"h5divided"), not ascii

Switch to "h5" or "h5divided" output if you need checkpointing (see Output Control Keywords).

Unused Keys in the Input Deck

“input deck key … was never used”: printed at startup for a key in the input deck that SLUG never reads, e.g.:

slug: warning: input deck key 'output.n_trial' (line 18) was never used; did you mean 'n_trial'?

The run continues, but the key had no effect, so the setting it was meant to control is at its default. The message names the key with its section (output.n_trial is n_trial in the [output] section) and the line it is on. The usual causes are:

  • The key is in the wrong section. Here n_trial belongs at the top level of the deck, outside any [section], so it must appear above the first [section] header. The message says “did you mean” when it finds the same name where SLUG looks for it. See The SLUG Input Deck for which section each keyword belongs in.

  • The key is misspelled, or has the wrong capitalization (keywords are case sensitive, so alphafe is not alphaFe). The message suggests the keyword you probably meant if there is a close match. This only applies to optional keywords: a required keyword that is misspelled is instead reported as missing, as described above.

  • A table is numbered wrongly. For example, a [yields.channel3] with no [yields.channel2] is never read, because SLUG stops at the first missing number, and its keys are each reported.

Keys that are valid but not used for this particular simulation, such as nebular.log_U when nebular.compute_neb is false, do not produce this warning; raise verbosity to 1 to see them listed, with the reason each was skipped (see Unused Keywords). If you want a warning like this to stop SLUG instead, set strict_input = true at the top level of the deck:

SimControls: strict_input is set, but the input deck has keys that were never used:
  input deck key 'output.n_trial' (line 19) was never used; did you mean 'n_trial'?

Yield Errors

The [yields] section of the input deck (see Yields Control Keywords) is checked at startup, so a mistake in it stops SLUG before any simulation runs, with a message that names the problem. The common ones are below; see Yields for the yield models available and what each covers.

The requested [Fe/H] is outside the range of the yield model:

slug: simulation failed: YieldChannel: requested [Fe/H] range [-0.500000,
-0.500000] extends outside the range available for channel 'ccsn', model
'sukhbold16' ([0.000000, 0.000000])

The [Fe/H] of the simulated population (stars.FeH) must lie within the range of [Fe/H] that the yield model tabulates, and the message reports both the range you asked for and the range the model provides. A model tabulated at a single [Fe/H] can only be used with exactly that value: sukhbold16, for example, is available only at [Fe/H] = 0. Either change stars.FeH or choose a model whose range covers it (see Standard Yield Models for the range of each standard model).

The registry has no such model:

slug: simulation failed: YieldChannel: registry .../data/yields/yields.toml has
no model 'kobayashi06_11' for channel 'massive_star_winds'

Either the model name is misspelled, or the model is not available for the channel you paired it with – the registry lists the models for each channel separately, and some models (like kobayashi06_11, which has supernova yields only) provide only one. The registry named in the message is the one that was actually searched, which is useful if you have set yields.registry to a custom one. If the registry file itself cannot be found (YieldChannel: registry ... not found), the same file-resolution rules apply as for the data files described under “Data Files Not Found” above.

A channel or model is missing or not recognized:

SimControls: yields.channel1.channel = 'supernova' is not a recognized yield channel
getTOMLKeyWithError: required key yields.channel1.model not found

Every [yields.channelN] table needs both a channel and a model, and channel must be one of the channels described in Yields. Note also that channels must be numbered consecutively from 1: SLUG stops at the first missing number and ignores any later table, so a [yields.channel3] with no [yields.channel2] does not stop the run, but contributes nothing to the output. Each of its keys is reported as unused, e.g. slug: warning: input deck key 'yields.channel3.model' (line 30) was never used (see Unused Keys in the Input Deck). If a channel you expected is missing from the output, check the numbering.

Problems with the isotope list:

Yields::rebuildYieldGrid: the given isotopes list does not intersect any isotope
tabulated by any loaded channel

SimControls: yields.isotopes entry 'H' is not a valid isotope specifier (expected
an element symbol followed by a mass number, e.g. 'H1', 'Na22', or 'fe56')

SimControls: yields.isotopes entry 'Xx12' names an unrecognized element symbol 'Xx'

SimControls: yields.isotopes entry 'Fe999' does not correspond to a known isotope
in the isotope table

The first means that none of the isotopes you listed is tabulated by the yield models you selected, or is a decay product of an isotope they tabulate – a typo is the most likely cause, but the isotope may simply not be one of those the model provides. The others mean that an entry in yields.isotopes is not a valid isotope name: each must be an element symbol followed by a mass number, with no space between them. A valid isotope that the models do not tabulate is not an error as long as at least one other entry matches. See the description of isotopes in Yields Control Keywords.

The mass range of a channel is invalid:

YieldChannel::rebuildYieldGrid: mMin (30.000000) must be strictly less than mMax
(20.000000)

m_min and m_max must both be positive, and m_min must be less than m_max. Remember that an omitted m_max defaults to the highest mass tabulated by the model, so setting m_min above that mass produces this error unless you also give a larger m_max.

Yields are requested but would never be written:

SimControls: yield channels were given, but output.write_cluster_yields and
output.write_galaxy_yields are both false (or this is a cluster-type simulation
and output.write_cluster_yields is false), so the computed yields would never be
written

You have defined at least one yield channel but turned off every output that would contain the result. For a cluster simulation output.write_cluster_yields must be true; for a galaxy simulation at least one of output.write_cluster_yields and output.write_galaxy_yields must be. Remove the yield channels if you do not actually want yields, or see Output Control Keywords.

Runtime Warnings and Errors

“stars … will be treated as having zero luminosity”: printed at startup if the IMF’s minimum mass is lower than the lowest mass covered by the selected track set, e.g.:

slug: warning: minimum mass in selected tracks is 0.1 but IMF minimum
mass is 0.08; stars with masses from 0.08 to 0.1 will be treated as
having zero luminosity

This is a warning, not an error – the run continues, but any star drawn in that mass gap contributes no light, yield, or feedback to the output. If this matters for your science case, either pick a track set with wider mass coverage or restrict the IMF’s own range; see Stellar Tracks for the mass range of each standard track set.

SLUG exits with an error partway through spectral synthesis: this means a star’s properties (temperature, gravity, composition) fell outside the coverage of every atmosphere model in the chain given by spectra.model. The default chain (model = "default") is assembled to cover essentially the full range produced by the standard tracks, so this is most likely if you’ve selected a single non-default atmosphere library, or a non-standard track set with more extreme properties than the defaults expect – see Alternative Atmosphere Models for how the model chain is searched and what to do about gaps in coverage.

A run appears to hang or produce no output: increase verbosity in the input deck (see Top-level Keywords). At verbosity = 1 SLUG prints a line when the run starts and finishes; at verbosity = 2 it also prints a line every time an individual Monte Carlo trial starts, which is usually enough to tell whether the run is actually progressing or has stalled (e.g. waiting on a slow filesystem for output).

Restarting and Checkpointed Runs

build/slug --restart/-R (or restart=True from Python) only works with HDF5 output that was actually checkpointed – see the “Checkpointing and Batch Runs” section of Running a SLUG Simulation for how to enable checkpointing and restart from it. Common mistakes:

  • Passing --restart to an ascii-output run: rejected immediately with slug: --restart/-R is not supported with ascii output, since ASCII output has no checkpoint to resume from.

  • Restarting into a fresh output directory, or after moving/renaming the original output file: SLUG resumes by finding the most recent checkpoint in the output file named by the current input deck’s own model_name/out_dir, so a restart only works if those still point at the original run’s own output.

Cloudy Post-Processing

Running slug_reader.run_cloudy (see Cloudy Nebular Processing) needs a working Cloudy installation, located either via an explicit path or the CLOUDY_DIR environment variable. If neither is set correctly, you’ll see one of:

find_cloudy_executable: no cloudy_path given, and CLOUDY_DIR is not set
in the environment

find_cloudy_executable: no executable cloudy binary found at <path>

The first means CLOUDY_DIR was never set (and no explicit path was passed); the second means it was set, but $CLOUDY_DIR/cloudy.exe either doesn’t exist or isn’t executable – double-check that CLOUDY_DIR points at the directory containing the compiled cloudy.exe (Cloudy’s source directory after building it), not Cloudy’s top-level install directory.

Getting Further Help

If a problem doesn’t match anything above, Tests describes how to run SLUG’s own test suite, which can help distinguish a local build/data problem (tests fail) from a problem specific to your own input deck (tests pass). Include the exact error message, your input deck, and the output of ctest -L quick when reporting an issue.