pyfvcom2.namelist module

class pyfvcom2.namelist.NamelistManager(casename: str = 'casename', fabm: bool = False)

Bases: object

Manager for FVCOM run namelists.

Holds a complete FVCOM namelist configuration with sensible defaults and exposes methods to update individual entries before writing to an ASCII .nml file.

The defaults correspond to a barotropic, tide-only cold-start run with no surface forcing, rivers, or data assimilation. The only mandatory entries that have no defaults are NML_CASE / START_DATE and NML_CASE / END_DATE; everything else is pre-populated.

Parameters:

  • casename – Model case name used to construct default file-path strings. Defaults to 'casename'.

  • fabm – If True, add FABM output controls to the relevant sections and append an NML_FABM section. Defaults to False.

Examples

>>> nml = NamelistManager(casename='tamar_v09')
>>> nml.update('NML_CASE', 'START_DATE', '2020-05-01 00:00:00')
>>> nml.update('NML_CASE', 'END_DATE',   '2020-06-01 00:00:00')
>>> nml.update('NML_INTEGRATION', 'EXTSTEP_SECONDS', 2.0)
>>> nml.update('NML_PHYSICS', 'TEMPERATURE_ACTIVE', True)
>>> nml.update_ramp(24)        # 24-hour ramp
>>> nml.write('tamar_v09_run.nml')
update(section: str, entry: str, value=None, fmt: str | None = None) → None

Update the value and/or format specifier of a namelist entry.

Parameters:

  • section – Section name (e.g. 'NML_CASE'). A leading '&' is accepted and stripped.

  • entry – Entry name within the section.

  • value – New value. bool is converted to 'T'/'F' automatically. Pass None to leave unchanged.

  • fmt – New Python format specification string (e.g. 'f', '.3f', 'd'). Pass None to leave unchanged.

Raises:

  • KeyError – If section or entry does not exist.

  • PyFVCOM2ValueError – If neither value nor fmt is supplied.

update_nesting_interval(target_interval: int = 900) → None

Find and set a NCNEST_OUT_INTERVAL compatible with the model.

Searches candidate intervals from 60 s up to ten times target_interval (in 60 s steps) and selects the valid candidate closest to target_interval.

Parameters:

target_interval – Target interval in seconds. Defaults to 900 s.

Raises:

PyFVCOM2ValueError – If no suitable interval is found — try a different target_interval, NCNEST_BLOCKSIZE, or EXTSTEP_SECONDS.

update_nudging(recovery_time: float) → None

Set OBC nudging timescales from a physical recovery time.

Computes the dimensionless FVCOM nudging timescale (EXTSTEP_SECONDS / recovery_time_seconds) and applies it to temperature, salinity, and — when FABM is enabled — FABM OBC nudging.

Parameters:

recovery_time – Recovery time in hours.

update_ramp(duration: float) → None

Set IRAMP to the number of external time steps for duration hours.

Parameters:

duration – Ramp duration in hours.

valid_nesting_timescale(interval: float | None = None) → bool

Check whether a nesting output interval is compatible with the model.

The simulation duration must be evenly divisible by NCNEST_OUT_INTERVAL × NCNEST_BLOCKSIZE, and the quotient must be evenly divisible by EXTSTEP_SECONDS.

Parameters:

interval – Candidate interval in seconds. If None, reads the current NCNEST_OUT_INTERVAL value from the config.

Returns:

True if the interval is compatible, False otherwise.

value(section: str, entry: str)

Return the current value of a namelist entry.

Parameters:

  • section – Section name (e.g. 'NML_CASE'). A leading '&' is accepted and stripped.

  • entry – Entry name within the section.

Returns:

The current value (str, int, float, or None).

Raises:

KeyError – If section or entry does not exist.

write(path: str) → None

Write the namelist configuration to an ASCII .nml file.

Before writing, None-valued *_FIRST_OUT entries and the dye release start/stop are back-filled from NML_CASE / START_DATE and NML_CASE / END_DATE.

Parameters:

path – Output file path.

Raises:

PyFVCOM2ValueError – If START_DATE or END_DATE have not been set, if NCNEST_ON is 'T' but the nesting interval is invalid, or if any other mandatory entry is still None at write time.