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.

Args:

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.

Args:

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.

Args:

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.

Args:

recovery_time: Recovery time in hours.

update_ramp(duration: float) → None

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

Args:

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.

Args:

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.

Args:

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.

Args:

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.