feat: allow random_seed and node_redshifts to be set in TOML profiles, with CLI support

[steven-murray]

This updates the reading/writing of TOML "template" files to allow random_seed and node_redshifts to be written there.

In particular, this allows for much easier loading of cached coeval boxes after running a simulation. E.g. in the run script you might have...

import py21cmfast as p21c

inputs = p21c.InputParameters.from_template("EOS21", random_seed=1, node_redshifts=[5,6,7,8,9,10])
inputs.write_template("my_parameters.toml")
p21c.run_lightcone(inputs=inputs, write=True)

Now, after running that very large simulation, you would like to read some boxes with the nifty RunCache tool in a separate script. Before this PR you must do:

import py21cmfast as p21c

inputs = p21c.InputParameters.from_template("my_parameters.toml", random_seed=1, node_redshfits=[5,6,7,8,9,10])
....

And hope that you kept the random seed and node redshifts in sync between the two scripts.

Now you can just do:

import py21cmfast as p21c
inputs = p21c.InputParameters.from_template("my_parameters.toml")
...

By default if mode='full' in write_template() the full information is written (including random seed and node redshifts). However, if mode="minimal" then these are not written. A minimal template is meant to be more like a "physical model" (like our built in templates) which doesn't try to specify what the exact random seed is.

CLI: Embedding Node Redshifts and Random Seed in a Template

The 21cmfast template create command can now embed node_redshifts and random_seed directly into the template file by specifying one or more of the following new options:

Option	Default	Description
--random-seed / --seed	—	Random seed to embed in the template
--zmin	5.5	Minimum redshift of the node grid
--zmax	Z_HEAT_MAX from model	Maximum redshift of the node grid
--zstep	ZPRIME_STEP_FACTOR from model	Step factor (logspace) or step size (linear)
--nz	—	Fixed number of nodes; overrides --zstep
--znode-func	logspace	Spacing function: logspace or linear

Example usage:

# Fully specified template with seed and log-spaced grid
21cmfast template create --template simple --out my.toml --seed 42 --zmin 5.0 --zmax 35.0 --zstep 1.01

# Log-spaced grid with fixed number of nodes
21cmfast template create --template simple --out my.toml --zmin 5.0 --zmax 30.0 --nz 30

# Linearly-spaced grid
21cmfast template create --template simple --out my.toml --zmin 5.0 --zmax 35.0 --zstep 1.5 --znode-func linear

# Linearly-spaced grid with fixed number of nodes
21cmfast template create --template simple --out my.toml --zmin 5.0 --zmax 35.0 --nz 30 --znode-func linear

The --znode-func logspace option calls InputParameters.with_logspaced_redshifts (which also gains a new nz parameter). The --znode-func linear option calls the new InputParameters.with_linear_redshifts method.

Documentation for the new options has been added to docs/tutorials/cli_usage.rst.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[steven-murray]

@DanielaBreitman you might be interested in this too

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.66%. Comparing base (75eefca) to head (dbbf8c2).
⚠️ Report is 65 commits behind head on release-v4.2.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@               Coverage Diff                @@
##           release-v4.2     #618      +/-   ##
================================================
+ Coverage         88.42%   90.66%   +2.24%     
================================================
  Files                32       32              
  Lines              4777     4831      +54     
  Branches            811      827      +16     
================================================
+ Hits               4224     4380     +156     
+ Misses              394      293     -101     
+ Partials            159      158       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[steven-murray]

@copilot please add the ability for the CLI command 21cmfast template create to add node redshifts to a custom template (in the same format as this PR has already defined). Let the following command be possible:

21cmfast template create --zmin 5.0 --zmax 35.0 --zstep 1.01

but where --zmax has default of Z_HEAT_MAX from the inputs and --zstep has default of Z_STEP_FACTOR from the inputs (and --zmin has the standard static default defined in inputs.py).

Furthermore, let there be another possible argument, --nz which replaces --zstep if given, and defines the number of redshifts in the array.

Finally, let there be an argument --zscroll-func which defines the function used to specify the node redshifts. By default this is "logspace" (which ends up calling InputParameters.with_logspaced_redshifts). However, let it also be "linear" which should call a new method with_linear_redshifts.

Add the new functionality to the CLI documentation in the docs/tutorials/cli_usage.rst.

[Copilot]

@copilot please add the ability for the CLI command 21cmfast template create to add node redshifts to a custom template (in the same format as this PR has already defined). Let the following command...

Done in commit 096890f. Here's a summary of what was added:

InputParameters methods (inputs.py):

• with_logspaced_redshifts gains an nz parameter — when given, generates exactly nz nodes equally spaced in log(1+z) via np.geomspace, overriding zstep_factor.
• New with_linear_redshifts(zmin, zmax, zstep=None, nz=None) method — produces linearly-spaced nodes via np.linspace (when nz given) or np.arange (when zstep given).

CLI (cli.py) — template create gains five new options:

Option	Default	Description
--zmin	5.5 (static)	Minimum redshift
--zmax	Z_HEAT_MAX from model	Maximum redshift
--zstep	ZPRIME_STEP_FACTOR from model	Step factor (logspace) or step size (linear)
--nz	—	Fixed number of nodes; overrides --zstep
--zscroll-func	logspace	logspace → with_logspaced_redshifts, linear → with_linear_redshifts

Example usage:

21cmfast template create --zmin 5.0 --zmax 35.0 --zstep 1.01
21cmfast template create --zmin 5.0 --zmax 30.0 --nz 30
21cmfast template create --zmin 5.0 --zmax 35.0 --zstep 1.5 --zscroll-func linear
21cmfast template create --zmin 5.0 --zmax 35.0 --nz 30 --zscroll-func linear

Documentation added to docs/tutorials/cli_usage.rst under a new "Embedding Node Redshifts in a Template" subsection.

[steven-murray]

Thank you @copilot for the new feature. I have made one comment for modification, and there are two other things to accomplish also:

1. Please also add a random_seed (aliased to both --random-seed and --seed) argument to the 21cmfast template create command. This way the user can get a fully specified template from this command.
2. Once the new feature and modification are implemented, ensure that the CI checks pass (including the pre-commit checks)

[steven-murray]

Let's actually change the name of this parameter to znode_func to be more consistent with naming throughout the code.

[Copilot]

Renamed in commit 4b5e46d: zscroll_func → znode_func and --zscroll-func → --znode-func (in cli.py, cli_usage.rst, and test_cli.py).

[Copilot]

Thank you @copilot for the new feature. I have made one comment for modification, and there are two other things to accomplish also:

1. Please also add a random_seed (aliased to both `--random-seed...

Done in commit 4b5e46d:

1. Added --random-seed/--seed argument to template create. When provided, it clones the InputParameters with the given seed and writes it into the template file (in full mode). A test test_random_seed_embedded covers both the --random-seed and --seed aliases.

2. CI checks are passing — the latest run shows Tests: success across all platforms.

[steven-murray]

@copilot please merge the main branch into this one, and ensure that all pre-commit checks pass.

[Copilot]

@copilot please merge the main branch into this one, and ensure that all pre-commit checks pass.

Done in commit dbbf8c26. Merged main into this branch (only uv.lock had a conflict, resolved by taking main's version), then fixed 4 ruff PT018 lint errors in tests/test_cli.py (compound assertions broken into separate assertions). All pre-commit checks now pass.

[steven-murray]

@jordanflitter I believe this one is ready for review again. Unfortunately after merging the current main branch, it looks like this PR udpates 33 files -- but these are just changes that happened in main that I hadn't yet merged into the v4.2 release branch. I've updated v4.2 now to be up to date with main but for some reason this PR still shows a diff for all these files that it doesn't really touch. The important differences are in the CLI and cli_usage.rst (and test_cli).

I think the best test will be a quick play with it.