SubSurfaceComponent

class unifhy.SubSurfaceComponent(saving_directory, timedomain, spacedomain, dataset=None, parameters=None, constants=None, records=None, io_slice=None)

Bases: unifhy.component.Component

The SubSurfaceComponent is simulating the hydrological processes in the subsurface compartment of the hydrological cycle.

Instantiation

Parameters

saving_directory: str

The path to the directory where to save the component dump and record files.

timedomain: TimeDomain object

The temporal dimension of the Component.

spacedomain: SpaceDomain object

The spatial dimension of the Component.

dataset: DataSet object, optional

The collection of input data required by the Component (i.e. ‘dynamic’ and/or ‘static’ and/or ‘climatologic’). The input data must always be compatible in space with spacedomain, and compatible in time with timedomain for the ‘dynamic’ kind, and with the ‘frequency’ for the ‘climatologic’ kind (see Tab. 2 for details).

parameters: dict, optional

The parameter values for the Component. Each key must correspond to a parameter name, and each value can be a cf.Field (with units), a cf.Data (with units), or a sequence of 2 items data and units (in this order).

If it is a cf.Field, it must contains data for all spatial elements in the region covered by the component’s spacedomain. If it is a cf.Data or sequence of 2 items, underlying data can be a scalar or an array (of the same shape as the component’s spacedomain).

Parameter example:

parameters={
    'parameter_a': (120, 'm s-1')
}

Parameter example:

parameters={
    'parameter_a': cf.Data(120, 'm s-1')
}

Parameter example:

parameters={
    'parameter_a': ([130, 110, 120], 'm s-1')
}

Parameter example:

parameters={
    'parameter_a': (numpy.array([130, 110, 120]), 'm s-1')
}

Parameter example:

parameters={
    'parameter_a': cf.Data([130, 110, 120], 'm s-1')
}

constants: dict, optional

The constant values for the Component for which adjustment is desired. Each key must correspond to a constant name, and each value must either be a cf.Data (with units, where data must be a scalar) or a sequence of 2 items data and units (in this order, where data must be a scalar).

Parameter example:

constants={
    'constant_a': (1000, 'kg m-3')
}

Parameter example:

constants={
    'constant_a': cf.Data(1000, 'kg m-3')
}

records: dict, optional

The desired records from the Component. Each key must be a valid variable recordable for the component chosen (i.e. outwards, outputs, and states), each value is a dict of recording temporal resolutions as datetime.timedelta for keys and aggregation methods as a sequence of str for values.

Parameter example:

records={
    'output_a': {
        timedelta(days=1): ['sum'],
        timedelta(weeks=1): ['min', 'max']
    },
    'output_b': {
        timedelta(days=1): ['mean']
    }
}

The aggregation methods supported are listed in the table below.

method	description
`'point'`	The instantaneous value at the given elapsed timedelta.
`'sum'`	The accumulation of the values during the given elapsed timedelta.
`'mean'`	The average of the values during the given elapsed timedelta.
`'min'`	The minimum amongst the values during the elapsed timedelta.
`'max'`	The maximum amongst the values during the elapsed timedelta.

The recording temporal resolutions must be multiples of the component temporal resolution, and they must be divisors of the component simulation period.

io_slice: int, optional

The length of the time slice to use for input/output operations. This corresponds to the number of component timesteps to read/write at once. If not set, its default value is 100 (arbitrary).

initialise_states_from_dump(dump_file, at=None)

Initialise the states of the Component from a dump file.

Parameters

dump_file: str

A string providing the path to the netCDF dump file containing values to be used as initial conditions for the states of the Component.

at: datetime object, optional

The snapshot in time to be used for the initial conditions. Must be any datetime type (except numpy.datetime64). Must be contained in the ‘time’ variable in dump_file. If not provided, the last index in the ‘time’ variable in dump_file will be used.

Note: if a datetime is provided, there is no enforcement of the fact that this datetime must correspond to the initial datetime in the simulation period for the Component, and it is only used as a means to select a specific snapshot in time amongst the ones available in the dump file.

Returns

datetime object: The snapshot in time that was used for the initial conditions.

revive_record_streams_from_dump(dump_file_pattern, timedomain=None, at=None)

Revive the record streams of the Component from a dump file.

Parameters

dump_filepath_pattern: str

A string providing the path to the netCDF dump file containing values to be used as initial conditions for the record streams of the Component. Note, curly brackets {} should be used where the record stream delta should be used.

Parameter example:

dump_file_pattern='out/dummy_surfacelayer_run_'
                  'dump_record_stream_{}.nc'

timedomain: TimeDomain, optional

This is required if the run to be revived is a spin-up one. Indeed, until the spin_up method is called, the TimeDomain of the Component is the one of its main run.

at: datetime object, optional

The snapshot in time to be used for the initial conditions. Must be any datetime type (except numpy.datetime64). Must be contained in the ‘time’ variable in dump file. If not provided, the last index in the ‘time’ variable in dump file will be used.

Returns

datetime object: The snapshot in time that was used for reviving the record streams.

property constants: Return the collection of adjusted constant values for the Component as a dict. Potentially returning an empty dictionary if no default constant value is adjusted.

property current_datetime: Return the current datetime at any stage during the simulation as a datetime object.

property dataset: Return the collection of variables forming the dataset for the Component as a DataSet object.

property initialised_states: Return whether initial conditions for component states have already been set as a bool.

property parameters: Return the collection of parameter values for the Component as a dict.

property records: Return the collection of desired records to be saved for the Component as a dict. Potentially returning an empty dictionary if no record are desired.

property spacedomain: Return the spatial configuration of the Component as a SpaceDomain object.

property spaceshape: Return the length of each dimension in the spatial configuration of the Component as a tuple of int.

property timedelta_in_seconds: Return the number of seconds separating two consecutive timestamps in the temporal configuration of the Component as a float.

property timedomain: Return the temporal configuration of the Component as a TimeDomain object.

Metadata properties

`inwards_metadata`	Return details on the component inward transfers as a `str`.
`outwards_metadata`	Return details on the component outward transfers as a `str`.
`inputs_metadata`	Return details on the component input data as a `str`.
`parameters_metadata`	Return details on the component parameters as a `str`.
`constants_metadata`	Return details on the component constants as a `str`.
`states_metadata`	Return details on the component states as a `str`.
`outputs_metadata`	Return details on the component outputs as a `str`.

Methods to query special data requirements

`requires_land_sea_mask`()	Return `True` if land sea mask must be available in the component spacedomain, otherwise return `False`.
`requires_flow_direction`()	Return `True` if flow direction must be available in the component spacedomain, otherwise return `False`.
`requires_cell_area`()	Return `True` if cell area must be available in the component spacedomain, otherwise return `False`.