Forcings .bc file

The forcings .bc files contain forcing data for point locations, for example time series input for a boundary condition. Various quantities and function types are supported.

The forcings file is represented by the classes below.

Model

Representation of a .bc file in various classes.

Most relevant classes are:

• ForcingModel: toplevel class containing the whole .bc file contents.
• ForcingBase subclasses: containing the actual data columns, for example: TimeSeries, HarmonicComponent, AstronomicComponent, HarmonicCorrection, AstronomicCorrection, Constant, T3D.

Astronomic (ForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with astronomic components data.

AstronomicCorrection (ForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with astronomic components correction data.

Constant (ForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with constant value data.

ForcingBase (DataBlockINIBasedModel) pydantic-model

The base class of a single [Forcing] block in a .bc forcings file.

Typically subclassed, for the specific types of forcing data, e.g, Harmonic. This model is for example referenced under a ForcingModel.forcing[..].

__repr__(self) -> str special

Return repr(self).

Source code in hydrolib/core/dflowfm/bc/models.py

def __repr__(self) -> str:
    data = dict(self)
    data["datablock"] = "<omitted>"
    representable = BaseModel.construct(**data)
    return str(representable)

validate(v) classmethod

Try to initialize subclass based on the function field. This field is compared to each function field of the derived models of ForcingBase or models derived from derived models. The derived model with an equal function type will be initialized.

Exceptions:

Type	Description
ValueError	When the given type is not a known structure type.

Source code in hydrolib/core/dflowfm/bc/models.py

@classmethod
def validate(cls, v):
    """Try to initialize subclass based on the `function` field.
    This field is compared to each `function` field of the derived models of `ForcingBase`
    or models derived from derived models.
    The derived model with an equal function type will be initialized.

    Raises:
        ValueError: When the given type is not a known structure type.
    """

    # should be replaced by discriminated unions once merged
    # https://github.com/samuelcolvin/pydantic/pull/2336
    if isinstance(v, dict):
        function_string = v.get("function", "").lower()
        function_type = get_type_based_on_subclass_default_value(
            cls, "function", function_string
        )

        if function_type is not None:
            return function_type(**v)

        else:
            raise ValueError(
                f"Function of {cls.__name__} with name={v.get('name', '')} and function={v.get('function', '')} is not recognized."
            )
    return v

ForcingData

Data type that selects from three different types of forcing data: * a scalar float constant * "realtime" keyword, indicating externally controlled. * A ForcingModel coming from a .bc file.

ForcingGeneral (INIGeneral) pydantic-model

[General] section with .bc file metadata.

ForcingModel (INIModel) pydantic-model

The overall model that contains the contents of one .bc forcings file.

This model is for example referenced under a ExtModel.boundary[..].forcingfile[..].

Harmonic (ForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with harmonic components data.

HarmonicCorrection (ForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with harmonic components correction data.

QHTable (ForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with Q-h table data.

QuantityUnitPair (BaseModel) pydantic-model

A .bc file header lines tuple containing a quantity name, its unit and optionally a vertical position index.

RealTime (str, Enum)

Enum class containing the valid value for the "realtime" reserved keyword for real-time controlled forcing data, e.g., for hydraulic structures.

This class is used inside the ForcingData Union, to force detection of the realtime keyword, prior to considering it a filename.

realtime

str: Realtime data source, externally provided

T3D (VectorForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with 3D timeseries data.

get_number_of_repetitions(values: Dict) -> int classmethod

Gets the number of expected quantityunitpairs for each vector element. Defaults to 1.

Source code in hydrolib/core/dflowfm/bc/models.py

@classmethod
def get_number_of_repetitions(cls, values: Dict) -> int:
    verticalpositions = values.get("vertpositions")
    # Since the renaming root validator may not have been run yet, in this
    # method we explicitly check old keywords for backwards compatibility:
    if verticalpositions is None:
        # try to get the value from any of the older keywords
        for old_keyword in cls._keys_to_rename["vertpositions"]:
            verticalpositions = values.get(old_keyword)
            if verticalpositions is not None:
                break

    if verticalpositions is None:
        raise ValueError("vertPositions is not provided")

    number_of_verticalpositions = (
        len(verticalpositions)
        if isinstance(verticalpositions, List)
        else len(verticalpositions.split())
    )

    return number_of_verticalpositions

rename_keys(values: Dict) -> Dict classmethod

Renames some old keywords to the currently supported keywords.

Source code in hydrolib/core/dflowfm/bc/models.py

@root_validator(allow_reuse=True, pre=True)
def rename_keys(cls, values: Dict) -> Dict:
    """Renames some old keywords to the currently supported keywords."""
    return rename_keys_for_backwards_compatibility(values, cls._keys_to_rename)

TimeInterpolation (str, Enum)

Enum class containing the valid values for the time interpolation.

block_from

str: Equal to that at the start of the time interval (latest specified time value).

block_to

str: Equal to that at the end of the time interval (upcoming specified time value).

linear

str: Linear interpolation between times.

TimeSeries (VectorForcingBase) pydantic-model

Subclass for a .bc file [Forcing] block with timeseries data.

rename_keys(values: Dict) -> Dict classmethod

Renames some old keywords to the currently supported keywords.

Source code in hydrolib/core/dflowfm/bc/models.py

@root_validator(allow_reuse=True, pre=True)
def rename_keys(cls, values: Dict) -> Dict:
    """Renames some old keywords to the currently supported keywords."""
    return rename_keys_for_backwards_compatibility(
        values,
        {
            "timeinterpolation": ["time_interpolation"],
        },
    )

VectorForcingBase (ForcingBase) pydantic-model

The base class of a single [Forcing] block that supports vectors in a .bc forcings file.

get_number_of_repetitions(values: Dict) -> int classmethod

Gets the number of expected quantityunitpairs for each vector element. Defaults to 1.

Source code in hydrolib/core/dflowfm/bc/models.py

@classmethod
def get_number_of_repetitions(cls, values: Dict) -> int:
    """Gets the number of expected quantityunitpairs for each vector element. Defaults to 1."""
    return 1

validate_and_update_quantityunitpairs(values: Dict) -> Dict classmethod

Validates and, if required, updates vector quantity unit pairs.

Parameters:

Name	Type	Description	Default
values	Dict	Dictionary of values to be used to validate or	required

Exceptions:

Type	Description
ValueError	When a quantity unit pair is found in a vector where it does not belong.
ValueError	When the number of quantity unit pairs in a vectors is not as expected.

Returns:

Type	Description
Dict	Dictionary of validates values.

Source code in hydrolib/core/dflowfm/bc/models.py

@root_validator(pre=True)
def validate_and_update_quantityunitpairs(cls, values: Dict) -> Dict:
    """
    Validates and, if required, updates vector quantity unit pairs.

    Args:
        values (Dict): Dictionary of values to be used to validate or
        update vector quantity unit pairs.

    Raises:
        ValueError: When a quantity unit pair is found in a vector where it does not belong.
        ValueError: When the number of quantity unit pairs in a vectors is not as expected.

    Returns:
        Dict: Dictionary of validates values.
    """
    quantityunitpairs = values["quantityunitpair"]
    vector = values.get("vector")
    number_of_element_repetitions = cls.get_number_of_repetitions(values)

    VectorForcingBase._process_vectordefinition_or_check_quantityunitpairs(
        vector, quantityunitpairs, number_of_element_repetitions
    )

    return values

VectorQuantityUnitPairs (BaseModel) pydantic-model

A subset of .bc file header lines containing a vector quantity definition, followed by all component quantity names, their unit and optionally their vertical position indexes.

__str__(self) -> str special

Return str(self).

Source code in hydrolib/core/dflowfm/bc/models.py

def __str__(self) -> str:
    return VectorQuantityUnitPairs._to_vectordefinition_string(
        self.vectorname, self.elementname
    )

VerticalInterpolation (str, Enum)

Enum class containing the valid values for the vertical position type, which defines what the numeric values for vertical position specification mean.

block

str: Equal to the value at the directly lower specified vertical position.

linear

str: Linear interpolation between vertical positions.

log

str: Logarithmic interpolation between vertical positions (e.g. vertical velocity profiles).

VerticalPositionType (str, Enum)

Enum class containing the valid values for the vertical position type.

percentage_bed

str: Percentage with respect to the water depth from the bed upward.

z_bed

str: Absolute distance from the bed upward.

z_datum

str: z-coordinate with respect to the reference level of the model.

z_surf

str: Absolute distance from the free surface downward.