pycequeau.simulations.parameters package

class pycequeau.simulations.parameters.BasinParameterBase(basin_structure: Basin)

Bases: SimulationParameterBase

Shared helper layer for parameter sections that depend on basin data.

This class groups the basin-derived calculations shared by simulation parameter sections:

• conversion of the watershed centroid latitude into the CEQUEAU xla code,

• determination of the maximum-insolation day from the meteorological file,

• empirical time-of-concentration estimators used to populate the transfer block.

compute_tc() → tuple[float, dict[str, float]]

Compute the basin time of concentration and return the contributing methods.

The exported transfer block stores both the average time of concentration and the individual empirical estimates used to derive it.

compute_xla() → int

Compute the CEQUEAU xla code from the basin centroid latitude.

CEQUEAU expects latitude in the compact integer form XXxx instead of a decimal degree value XX.xx. For example, 46.73 becomes 4673.

day_max_insolation(meteo_file_name: str) → int

Compute the CEQUEAU insolation day index from the meteorological forcing.

The CEQUEAU option structure uses jonei and joeva to represent the reference day of maximum insolation. This value is estimated from the day of year with the highest multi-annual mean tMax.

static normalize_numeric_for_mex(obj)

Recursively convert numeric values to float64-compatible structures.

static tc_giandotti(basin_area: float, main_channel_length: float, height_differences: float) → float

This method uses the Giandotti (1934) formulation to compute the time of concentration:

\[T_{c} = \frac{4\sqrt{A} + 1.5L}{0.8\sqrt{H}}\]

where:

• \(A\) is the area of the basin in \(\text{km}^{2}\)

• \(L\) is the length of the main channel in \(\text{km}\)

• \(H\) is the difference between the mean basin elevation and the outlet elevation

• \(T_{c}\) is the time of concentration in hours

This formula was calibrated on 12 basins with drainage areas between 170 and 70 000 \(\text{km}^{2}\).

The returned value is converted to days.

static tc_kirpich(main_channel_length: float, height_differences: float) → float

This method uses the Kirpich (1940) formulation to compute the time of concentration:

\[T_{c} = 0.0078 L^{0.77}S^{-0.385}\]

where \(L\) is the length of the main channel in \(ft\) and \(S\) is the mean basin slope in \(\text{m m}^{-1}\) computed as:

\[S = \frac{H_{max} - H_{min}}{L}\]

\(T_{c}\) is obtained in minutes and then converted to days.

static tc_pw(main_channel_length: float, height_differences: float) → float

This method uses the Department of Public Works (1995) formulation to compute the time of concentration:

\[T_{c} = 60 \left ( 11.9 \frac{L^{3}}{H} \right )^{0.385}\]

where:

• \(L\) is the length of the main channel in \(mi\)

• \(H\) is the maximum elevation difference in \(ft\)

• \(T_{c}\) is the time of concentration in \(min\)

The returned value is converted to days.

to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

class pycequeau.simulations.parameters.EvapotranspirationParameters(basin_structure)

Bases: BasinParameterBase

Evapotranspiration parameter structure for supported models.

The selected model controls which keys are exported in the evapo block.

apply_option_defaults(option: dict | None) → None

Propagate option-dependent values into the evapotranspiration blocks.

set_parameters(values: ndarray) → None

Populate the evapotranspiration section for all supported CEQUEAU models.

The exported structure contains one parameter block per supported model. The active evapotranspiration model is controlled separately through the simulation option block.

to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

class pycequeau.simulations.parameters.HydrologicalParameters(basin_structure)

Bases: BasinParameterBase

Container for the hydrological part of the CEQUEAU parameter structure.

This section groups the option, soil, initial-state, transfer, snowmelt, and evapotranspiration blocks that are required by the hydrological model.

property evapo: dict | None

property fonte: dict | None

classmethod from_values(basin_structure, flow_parameters: ndarray, initial_conditions: ndarray, transfer_parameters: ndarray, simulation_options: ndarray, snow_parameters: ndarray, evapotranspiration_parameters: ndarray, meteo_file_name: str) → HydrologicalParameters

Build the hydrological parameter group from the raw CEQUEAU input vectors.

This constructor hides the ordering dependencies of the setter-based API by computing the insolation day and propagating dependent values internally before returning the fully initialized section.

set_evapotranspiration(values: ndarray) → None

Populate the evapotranspiration structure.

set_initial_soil_conditions(values: ndarray) → None

Populate the initial storage conditions in solInitial.

set_option(values: ndarray, jonei: int | None) → None

Populate the simulation option block.

The jonei and joeva entries are computed from the basin meteorological forcing through day_max_insolation().

set_snowmelt(values: ndarray) → None

Populate the hydrological snowmelt structure.

set_soil(values: ndarray) → None

Populate the sol block.

The exported xla value is derived from the watershed centroid because CEQUEAU stores latitude as an integer code rather than decimal degrees.

set_transfer(values: ndarray) → None

Populate the transfer block and derive the basin travel time.

zn is exported as the average of the empirical time-of-concentration equations returned by compute_tc().

to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

class pycequeau.simulations.parameters.PycequeauParams(bassinVersant: Basin, hydrology: HydrologicalParameters | None = None, water_quality: WaterQualityParameters | None = None, *, ctp: float = 0.0, lac: float = 0.0, surface: float = 0.0)

Bases: BasinParameterBase

Top-level CEQUEAU parameter facade.

This class assembles pre-built hydrology and water-quality sections into the final CEQUEAU parameter dictionary and handles export to JSON/MAT formats.

create_parameter_structure()

Assemble and return the final CEQUEAU parameter dictionary.

export_parameter_structure_json(file_name: str = 'parameters.json')

Export the current parameter dictionary to JSON.

export_parameter_structure_mat(file_name: str = 'parameters.mat')

Export current parameter dictionary to MATLAB/Octave .mat format.

class pycequeau.simulations.parameters.SimulationParameterBase(basin_structure: Basin)

Bases: ABC

Shared base class for simulation-parameter sections.

Each parameter family is responsible for exporting its own CEQUEAU-compatible dictionary fragment through to_dict().

abstract to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

class pycequeau.simulations.parameters.SnowmeltParameters(basin_structure)

Bases: BasinParameterBase

Snowmelt parameter structure for the supported hydrological models.

The CEQUEAU parameter file stores several snowmelt model blocks in the fonte section. This class keeps the snow-specific defaults and model-dependent parameters in one place.

apply_option_defaults(option: dict | None, sol_initial: dict | None) → None

Inject option- and state-dependent values into the CEQUEAU snow block.

set_parameters(values: ndarray) → None

Populate the snowmelt parameter dictionaries.

Parameters:

• values –

  Ordered parameter vector used to populate the snowmelt structures. The first seven values correspond to the degree-day CEQUEAU model:

  strne_s, tfc_s, tfd_s, tsc_s, tsd_s, ttd, tts_s.

• CEQUEAU (The exported structure contains the)

• UEB

• blocks (and CemaNeige)

• options. (regardless of the active model selected in the simulation)

to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

class pycequeau.simulations.parameters.WaterQualityParameters(basin_structure)

Bases: BasinParameterBase

Top-level water-quality parameter group.

Water temperature is currently the only implemented quality module, but it is kept as a child structure so future quality components can be added cleanly.

property dli: dict

classmethod from_values(basin_structure, temperature_parameters: ndarray, temperature_model: int = 1) → WaterQualityParameters

Build the water-quality parameter group from raw model values.

property qualite: dict | None

set_temperature(values: ndarray, model: int = 1) → None

to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

class pycequeau.simulations.parameters.WaterTemperatureParameters(basin_structure)

Bases: BasinParameterBase

Water-temperature-specific parameters under the water-quality family.

At the moment the water-quality branch only contains the CEQUEAU water temperature model, but the container is intentionally scoped so additional quality modules can be added later without reshaping the top-level API.

classmethod from_values(basin_structure, values: ndarray, model: int = 1) → WaterTemperatureParameters

Build a water-temperature parameter section from a raw value vector.

set_model_parameters(values: ndarray, model: int = 1) → None

Populate the water-temperature parameter block.

The exported layout matches the qualite.cequeau.temperat structure expected by the CEQUEAU workflow.

to_dict() → dict

Return the CEQUEAU-compatible representation of the section.

Submodules

• pycequeau.simulations.parameters.base module
  • BasinParameterBase
    • BasinParameterBase.compute_tc()
    • BasinParameterBase.compute_xla()
    • BasinParameterBase.day_max_insolation()
    • BasinParameterBase.normalize_numeric_for_mex()
    • BasinParameterBase.tc_giandotti()
    • BasinParameterBase.tc_kirpich()
    • BasinParameterBase.tc_pw()
    • BasinParameterBase.to_dict()
  • SimulationParameterBase
    • SimulationParameterBase.to_dict()
• pycequeau.simulations.parameters.hydrology module
  • EvapotranspirationModel
    • EvapotranspirationModel.CEQUEAU
    • EvapotranspirationModel.KPENMAN
    • EvapotranspirationModel.MCGUINNESS
    • EvapotranspirationModel.MORTON
    • EvapotranspirationModel.PENMONT
    • EvapotranspirationModel.PRIESTLEYTAYLOR
  • EvapotranspirationParameters
    • EvapotranspirationParameters.apply_option_defaults()
    • EvapotranspirationParameters.set_parameters()
    • EvapotranspirationParameters.to_dict()
  • HydrologicalParameters
    • HydrologicalParameters.evapo
    • HydrologicalParameters.fonte
    • HydrologicalParameters.from_values()
    • HydrologicalParameters.set_evapotranspiration()
    • HydrologicalParameters.set_initial_soil_conditions()
    • HydrologicalParameters.set_option()
    • HydrologicalParameters.set_snowmelt()
    • HydrologicalParameters.set_soil()
    • HydrologicalParameters.set_transfer()
    • HydrologicalParameters.to_dict()
  • SnowmeltModel
    • SnowmeltModel.CEMA_NEIGE
    • SnowmeltModel.CEQUEAU
    • SnowmeltModel.UEB
  • SnowmeltParameters
    • SnowmeltParameters.apply_option_defaults()
    • SnowmeltParameters.set_parameters()
    • SnowmeltParameters.to_dict()
• pycequeau.simulations.parameters.parameters module
  • PycequeauParams
    • PycequeauParams.create_parameter_structure()
    • PycequeauParams.export_parameter_structure_json()
    • PycequeauParams.export_parameter_structure_mat()
• pycequeau.simulations.parameters.water_quality module
  • WaterQualityParameters
    • WaterQualityParameters.dli
    • WaterQualityParameters.from_values()
    • WaterQualityParameters.qualite
    • WaterQualityParameters.set_temperature()
    • WaterQualityParameters.to_dict()
  • WaterTemperatureParameters
    • WaterTemperatureParameters.from_values()
    • WaterTemperatureParameters.set_model_parameters()
    • WaterTemperatureParameters.to_dict()