pycequeau.simulations.parameters.base module

class pycequeau.simulations.parameters.base.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.base.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.