Requirements for perturbIC.py

[atteggiani]

Drafting some requirements for perturbIC.py to help out with refactoring / unit-testing / regression testing:

General requirements

Primary functionality: Perturb a UM initial condition (start dump) file and output a modified (perturbed) version.
Python version: >=3.10
Audience: Researchers / model users
Mode of use: Offline. To be run manually by the user. (Maybe also in scripts? To create different ensembles?? How?)
Interface type: CLI

Interface requirements

Inputs: Input file (positional argument) [UM start dump file, required]
Outputs: Output file (changed in-place or output path provided by the --output option)
Options:

• -a, --amplitude: amplitude of the perturbation [float, default = 0.01, optional]
• -s, -seed: seed for random perturbation reproducibility [int >=0, optional] (No default needs to be set, if not set seed=None.
• -o, --output: output path [optional] (if provided will not work in-place, otherwise it will)

Testing requirements

Unit-testing: Refactor script into multiple "single-task" functions that can be "easily" tested separately
Regression-testing:

• Test that output file has the desired fields perturbed. (This should also be done as a unit-test for the data before being written)
• Test that output of new script matches the output of the old script (using same seed) (To discuss best approach for this)

[atteggiani]

I think this can be a good starting point for the work that needs to be done on the perturbIC.py file.

@MartinDix
Please feel free to revise/add requirements to this list.

[atteggiani]

Some documentation on random seeding and best practices.