Development Guide
This page summarises the extension points that are most likely to matter when adding a parameter, adding a waveform wrapper or changing the ROQ construction logic.
Repository Map
Path |
Role |
|---|---|
|
Command-line entry point, output directory creation, logging, pool initialisation and top-level run loop. |
|
Lightweight package metadata, including |
|
Help text, config parsing, default values, active-parameter selection and training/test-value parsing. |
|
ROQ class, parameter transforms, basis construction, empirical-node selection and enrichment cycles. |
|
Waveform wrapper registry and model-specific input checks. |
|
Scalar product, normalisation, projection and Gram-Schmidt helper. |
|
Validation tests and diagnostic plots. |
|
Serial, multiprocessing and MPI pool adapters. |
|
Short implementation-check configs. |
|
Packaging metadata, dynamic version/readme configuration, core
dependencies, optional extras and the installed |
Adding A New Parameter
Parameter activation is controlled in JenpyROQ/initialise.py. A new
parameter needs four pieces of work.
Add a default range and test value to
default_params.Example pattern:
default_params["my_parameter"] = { "range": [0.0, 1.0], "test-value": 0.5, }
Update
check_skip_parameterso the parameter is active only for the intended flags or approximants.If the parameter should be active only when
my-flag = 1, the check should return1when the flag is absent or false:if key == "my_parameter" and not input_par["Waveform_and_parametrisation"]["my-flag"]: return 1
Add any new config flag to the default
input_par["Waveform_and_parametrisation"]dictionary and to the help string at the top ofinitialise.py.Use the parameter in the relevant waveform wrapper or parameter transform. The ROQ class passes active sampled parameters as a dictionary
pintogenerate_waveform.
Adding A Waveform Wrapper
The wrapper registry is the dictionary WfWrapper in
JenpyROQ/waveform_wrappers.py. A wrapper should:
accept
approximantand optionaladditional_waveform_paramsin__init__;implement
generate_waveform(self, p, deltaF, f_min, f_max, distance);return two arrays
hpandhcon the gridnp.arange(f_min, f_max + deltaF, deltaF)or an exactly compatible grid;validate unsupported parts of the requested parameter domain with explicit exceptions;
register itself by assigning
WfWrapper[approximant_name] = WrapperClass.
For optional dependencies, follow the existing pattern:
try:
import my_waveform_package
class WfMyModel:
...
WfWrapper["my-model"] = WfMyModel
except ModuleNotFoundError:
print("\nWarning: `my_waveform_package` module not found.\n")
ROQ Construction Changes
The main algorithmic stages are:
construct_corner_basis;construct_preselection_basis;interpolant_and_empirical_nodes;roqs;test_roq_errorinpost_processing.py.
When changing one of these stages, update the stored-array format only if the
reader in post-processing-only mode is updated at the same time. Existing
resumability depends on the names and shapes of files under
ROQ_data/linear and ROQ_data/quadratic.
Testing Checklist
For a narrow code change, run at least one short config that exercises the changed path. Examples:
python -m JenpyROQ --config-file config_files/Test_configs/config_test_IMRPv2.ini
python -m JenpyROQ --config-file config_files/Test_configs/config_test_MLGW-BNS.ini
For config-parser or docs changes, also run:
python -m JenpyROQ --help
sphinx-build -b html docs docs/_build/html
For MPI or multiprocessing changes, use a deliberately small training set first, then repeat with a representative production-sized training set.