Skip to content

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, TimeSeries. This model is for example referenced under a ForcingModel.forcing[..].

Attributes:

Name Type Description
name str

Unique identifier that identifies the location for this forcing data.
function str

Function type of the data in the actual datablock.
quantityunitpair List[QuantityUnitPair]

list of header line tuples for one or more quantities + their unit. Describes the columns in the actual datablock.

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. 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/io/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`.
    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):
        for c in cls.__subclasses__():
            if (
                c.__fields__.get("function").default.lower()
                == v.get("function", "").lower()
            ):
                v = c(**v)
                break
        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[..].

Attributes:

Name Type Description
general ForcingGeneral

[General] block with file metadata.
forcing List[ForcingBase]

List of [Forcing] blocks for all forcing definitions in a single .bc file. Actual data is stored in forcing[..].datablock from [hydrolib.core.io.ini.models.DataBlockINIBasedModel.datablock] or [hydrolib.core.io.ini.models.DataBlockINIBasedModel].

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 (tuple)

A .bc file header lines tuple containing a quantity name and its unit.

__getnewargs__(self) special

Return self as a plain tuple. Used by copy and pickle.

Source code in hydrolib/core/io/bc/models.py 
def __getnewargs__(self):
    'Return self as a plain tuple.  Used by copy and pickle.'
    return _tuple(self)

__new__(_cls, quantity: str, unit: str) special staticmethod

Create new instance of QuantityUnitPair(quantity, unit)

__repr__(self) special

Return a nicely formatted representation string

Source code in hydrolib/core/io/bc/models.py 
def __repr__(self):
    'Return a nicely formatted representation string'
    return self.__class__.__name__ + repr_fmt % self

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 (ForcingBase) pydantic-model

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

TimeInterpolation (str, Enum)

An enumeration.

TimeSeries (ForcingBase) pydantic-model

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

VerticalInterpolation (str, Enum)

An enumeration.

VerticalPositionType (str, Enum)

An enumeration.

Back to top