Hydrology

Note

This is the complete exposed API. Not all classes and functions are meant for the End-user, the documentation is a work in progress

class shyft.hydrology.GeoCellDataServer

Bases: instance

The server-side component for the shyft.hydrology geo_cell_data model repository.

__init__((GeoCellDataServer)self, (object)root_dir) → None :

Creates a server object that serves models from root_dir. The root_dir will be create if it does not exsists.

Parameters:

root_dir (str) – Path to the root-directory that keeps/will keep the model-files

get_listening_port((GeoCellDataServer)self) → int :

returns the port number it’s listening at for serving incoming request

get_max_connections((GeoCellDataServer)self) → int :

returns the maximum number of connections to be served concurrently

is_running((GeoCellDataServer)self) → bool :

true if server is listening and running

See also

start_server()

set_listening_ip((GeoCellDataServer)self, (object)ip) → None :

set the listening port for the service

Parameters:

ip (str) – ip or host-name to start listening on

Returns:

nothing.

Return type:

None

set_listening_port((GeoCellDataServer)self, (object)port_no) → None :

set the listening port for the service

Parameters:

• port_no (int) – a valid and available tcp-ip port number to listen on.

• 20000 (typically it could be) –

Returns:

nothing.

Return type:

None

set_max_connections((GeoCellDataServer)self, (object)max_connect) → None :

limits simultaneous connections to the server (it’s multithreaded, and uses on thread pr. connect)

Parameters:

max_connect (int) – maximum number of connections before denying more connections

See also

get_max_connections()

start_server((GeoCellDataServer)self) → int :

start server listening in background, and processing messages

See also

set_listening_port(port_no),is_running

Returns:

port_no. the port used for listening operations, either the value as by set_listening_port, or if it was unspecified, a new available port

Return type:

in

stop_server((GeoCellDataServer)self[, (object)timeout=1000]) → None :

stop serving connections, gracefully.

See also

start_server()

class shyft.hydrology.GeoCellDataClient

Bases: instance

The client api for the shyft.hydrology geo_cell_data model service.

__init__((GeoCellDataClient)self, (object)host_port, (object)timeout_ms) → None :

Creates a python client that can communicate with the corresponding server

close((GeoCellDataClient)self) → None :

Close the connection. It will automatically reopen if needed.

get_model_infos((GeoCellDataClient)self, (IntVector)mids[, (UtcPeriod)created_in=[not-valid-period>]) → ModelInfoVector :

returns all or selected model-info objects based on model-identifiers(mids)

Parameters:

• mids (IntVector) – empty = all, or a list of known exisiting model-identifiers

• created_in (UtcPeriod) – For which period you are interested in model-infos.

Returns:

model_infos. Strongly typed list of ModelInfo

Return type:

ModelInfoVector

property host_port

Endpoint network address of the remote server.

Type:

str

property is_open

If the connection to the remote server is (still) open.

Type:

bool

read_model((GeoCellDataClient)self, (object)mid) → GeoCellDataModel :

Read and return the model for specified model-identifier (mid)

Parameters:

mid (int) – the model-identifer for the wanted model

Returns:

13. The resulting model from the server

Return type:

Model

read_models((GeoCellDataClient)self, (IntVector)mids) → GeoCellDataModelVector :

Read and return the model for specified model-identifier (mid)

Parameters:

mids (Int64Vector) – A strongly typed list of ints, the model-identifers for the wanted models

Returns:

13. The resulting model from the server

Return type:

Model

property reconnect_count

Number of reconnects to the remote server that have been performed.

Type:

int

remove_model((GeoCellDataClient)self, (object)mid) → int :

Remove the specified model bymodel-identifier (mid)

Parameters:

mid (int) – the model-identifer for the wanted model

Returns:

ec. 0 or error-code?

Return type:

int

store_model((GeoCellDataClient)self, (GeoCellDataModel)m, (ModelInfo)mi) → int :

Store the model to backend, if m.id==0 then a new unique model-info is created and used

Parameters:

• m (Model) – The model to store

• mi (ModelInfo) – The model-info to store for the model

Returns:

mid. model-identifier for the stored model and model-info

Return type:

int

property timeout_ms

Timout for remote server operations, in number milliseconds.

Type:

int

update_model_info((GeoCellDataClient)self, (object)mid, (ModelInfo)mi) → bool :

Update the model-info for specified model-identifier(mid)

Parameters:

• mid (int) – model-identifer

• mi (ModelInfo) – The new updated model-info

Returns:

ok. true if success

Return type:

bool

class shyft.hydrology.GeoCellDataModel

Bases: instance

A model identifier and a geo-cell-data vector

__init__((GeoCellDataModel)arg1) → None

property geo_cell_data

a strongly typed list of geo-cell-data, the geo-personality of Shyft cells

Type:

GeoCellDataVector

property id

unique model identifier

Type:

int

class shyft.hydrology.StateServer

Bases: instance

The server-side component for the shyft.hydrology state model repository.

__init__((StateServer)self, (object)root_dir) → None :

Creates a server object that serves models from root_dir. The root_dir will be create if it does not exsists.

Parameters:

root_dir (str) – Path to the root-directory that keeps/will keep the model-files

get_listening_port((StateServer)self) → int :

returns the port number it’s listening at for serving incoming request

get_max_connections((StateServer)self) → int :

returns the maximum number of connections to be served concurrently

is_running((StateServer)self) → bool :

true if server is listening and running

See also

start_server()

set_listening_ip((StateServer)self, (object)ip) → None :

set the listening port for the service

Parameters:

ip (str) – ip or host-name to start listening on

Returns:

nothing.

Return type:

None

set_listening_port((StateServer)self, (object)port_no) → None :

set the listening port for the service

Parameters:

• port_no (int) – a valid and available tcp-ip port number to listen on.

• 20000 (typically it could be) –

Returns:

nothing.

Return type:

None

set_max_connections((StateServer)self, (object)max_connect) → None :

limits simultaneous connections to the server (it’s multithreaded, and uses on thread pr. connect)

Parameters:

max_connect (int) – maximum number of connections before denying more connections

See also

get_max_connections()

start_server((StateServer)self) → int :

start server listening in background, and processing messages

See also

set_listening_port(port_no),is_running

Returns:

port_no. the port used for listening operations, either the value as by set_listening_port, or if it was unspecified, a new available port

Return type:

in

stop_server((StateServer)self[, (object)timeout=1000]) → None :

stop serving connections, gracefully.

See also

start_server()

class shyft.hydrology.StateClient

Bases: instance

The client api for the shyft.hydrology state model service.

__init__((StateClient)self, (object)host_port, (object)timeout_ms) → None :

Creates a python client that can communicate with the corresponding server

close((StateClient)self) → None :

Close the connection. It will automatically reopen if needed.

get_model_infos((StateClient)self, (IntVector)mids[, (UtcPeriod)created_in=[not-valid-period>]) → ModelInfoVector :

returns all or selected model-info objects based on model-identifiers(mids)

Parameters:

• mids (IntVector) – empty = all, or a list of known exisiting model-identifiers

• created_in (UtcPeriod) – For which period you are interested in model-infos.

Returns:

model_infos. Strongly typed list of ModelInfo

Return type:

ModelInfoVector

property host_port

Endpoint network address of the remote server.

Type:

str

property is_open

If the connection to the remote server is (still) open.

Type:

bool

read_model((StateClient)self, (object)mid) → StateModel :

Read and return the model for specified model-identifier (mid)

Parameters:

mid (int) – the model-identifer for the wanted model

Returns:

13. The resulting model from the server

Return type:

Model

read_models((StateClient)self, (IntVector)mids) → StateModelVector :

Read and return the model for specified model-identifier (mid)

Parameters:

mids (Int64Vector) – A strongly typed list of ints, the model-identifers for the wanted models

Returns:

13. The resulting model from the server

Return type:

Model

property reconnect_count

Number of reconnects to the remote server that have been performed.

Type:

int

remove_model((StateClient)self, (object)mid) → int :

Remove the specified model bymodel-identifier (mid)

Parameters:

mid (int) – the model-identifer for the wanted model

Returns:

ec. 0 or error-code?

Return type:

int

store_model((StateClient)self, (StateModel)m, (ModelInfo)mi) → int :

Store the model to backend, if m.id==0 then a new unique model-info is created and used

Parameters:

• m (Model) – The model to store

• mi (ModelInfo) – The model-info to store for the model

Returns:

mid. model-identifier for the stored model and model-info

Return type:

int

property timeout_ms

Timout for remote server operations, in number milliseconds.

Type:

int

update_model_info((StateClient)self, (object)mid, (ModelInfo)mi) → bool :

Update the model-info for specified model-identifier(mid)

Parameters:

• mid (int) – model-identifer

• mi (ModelInfo) – The new updated model-info

Returns:

ok. true if success

Return type:

bool

class shyft.hydrology.StateModel

Bases: instance

A model identifier and a StateVector, where the vector can keep an uniform set of StateId of specified type

__init__((StateModel)arg1) → None

property id

unique model id

Type:

int

property states

kind of state vector with id

Type:

Any

class shyft.hydrology.ParameterServer

Bases: instance

The server-side component for the shyft.hydrology parameter model repository.

__init__((ParameterServer)self, (object)root_dir) → None :

Creates a server object that serves models from root_dir. The root_dir will be create if it does not exsists.

Parameters:

root_dir (str) – Path to the root-directory that keeps/will keep the model-files

get_listening_port((ParameterServer)self) → int :

returns the port number it’s listening at for serving incoming request

get_max_connections((ParameterServer)self) → int :

returns the maximum number of connections to be served concurrently

is_running((ParameterServer)self) → bool :

true if server is listening and running

See also

start_server()

set_listening_ip((ParameterServer)self, (object)ip) → None :

set the listening port for the service

Parameters:

ip (str) – ip or host-name to start listening on

Returns:

nothing.

Return type:

None

set_listening_port((ParameterServer)self, (object)port_no) → None :

set the listening port for the service

Parameters:

• port_no (int) – a valid and available tcp-ip port number to listen on.

• 20000 (typically it could be) –

Returns:

nothing.

Return type:

None

set_max_connections((ParameterServer)self, (object)max_connect) → None :

limits simultaneous connections to the server (it’s multithreaded, and uses on thread pr. connect)

Parameters:

max_connect (int) – maximum number of connections before denying more connections

See also

get_max_connections()

start_server((ParameterServer)self) → int :

start server listening in background, and processing messages

See also

set_listening_port(port_no),is_running

Returns:

port_no. the port used for listening operations, either the value as by set_listening_port, or if it was unspecified, a new available port

Return type:

in

stop_server((ParameterServer)self[, (object)timeout=1000]) → None :

stop serving connections, gracefully.

See also

start_server()

class shyft.hydrology.ParameterClient

Bases: instance

The client api for the shyft.hydrology parameter model service.

__init__((ParameterClient)self, (object)host_port, (object)timeout_ms) → None :

Creates a python client that can communicate with the corresponding server

close((ParameterClient)self) → None :

Close the connection. It will automatically reopen if needed.

get_model_infos((ParameterClient)self, (IntVector)mids[, (UtcPeriod)created_in=[not-valid-period>]) → ModelInfoVector :

returns all or selected model-info objects based on model-identifiers(mids)

Parameters:

• mids (IntVector) – empty = all, or a list of known exisiting model-identifiers

• created_in (UtcPeriod) – For which period you are interested in model-infos.

Returns:

model_infos. Strongly typed list of ModelInfo

Return type:

ModelInfoVector

property host_port

Endpoint network address of the remote server.

Type:

str

property is_open

If the connection to the remote server is (still) open.

Type:

bool

read_model((ParameterClient)self, (object)mid) → ParameterModel :

Read and return the model for specified model-identifier (mid)

Parameters:

mid (int) – the model-identifer for the wanted model

Returns:

13. The resulting model from the server

Return type:

Model

read_models((ParameterClient)self, (IntVector)mids) → ParameterModelVector :

Read and return the model for specified model-identifier (mid)

Parameters:

mids (Int64Vector) – A strongly typed list of ints, the model-identifers for the wanted models

Returns:

13. The resulting model from the server

Return type:

Model

property reconnect_count

Number of reconnects to the remote server that have been performed.

Type:

int

remove_model((ParameterClient)self, (object)mid) → int :

Remove the specified model bymodel-identifier (mid)

Parameters:

mid (int) – the model-identifer for the wanted model

Returns:

ec. 0 or error-code?

Return type:

int

store_model((ParameterClient)self, (ParameterModel)m, (ModelInfo)mi) → int :

Store the model to backend, if m.id==0 then a new unique model-info is created and used

Parameters:

• m (Model) – The model to store

• mi (ModelInfo) – The model-info to store for the model

Returns:

mid. model-identifier for the stored model and model-info

Return type:

int

property timeout_ms

Timout for remote server operations, in number milliseconds.

Type:

int

update_model_info((ParameterClient)self, (object)mid, (ModelInfo)mi) → bool :

Update the model-info for specified model-identifier(mid)

Parameters:

• mid (int) – model-identifer

• mi (ModelInfo) – The new updated model-info

Returns:

ok. true if success

Return type:

bool

class shyft.hydrology.ParameterModel

Bases: instance

A model identifier and a strongly typed dict, cpp-map, of stack parameters, suitable for use with a region-model matching the type.

__init__((ParameterModel)arg1) → None

property id

unique model id

Type:

int

property parameters

kind of parameter with id

Type:

Any

shyft.hydrology.parse_cf_time((str)reference) → UtcPeriod :

parses cf time unit string like hours since 1970-01-01 00:00:00 and returs an UtcPeriod, where the .start is the reference time and the .timespan() is the delta time, e.g. 3600.0 If the reference is illformed, then the returned period is not .valid() The intended usage is to get the reference time and time-delta of netcdf files, replacing the need of cftime python library.

Parameters:

reference (str) – netcdf time-reference

Returns:

16. p.valid()==True if well formed,p.start equal to the reference time, and p.timespan() equal to the time-delta specified

Return type:

UtcPeriod

shyft.hydrology.np_array(dv: DoubleVector)

convert flattened double-vector to numpy array :param dv:

Return type:

numpy array.

shyft.hydrology.StrGeoCellData(gcd)

class shyft.hydrology.ARegionEnvironment

Bases: instance

Contains all geo-located sources to be used by a Shyft core model

__init__((ARegionEnvironment)arg1) → None

static create_from_geo_ts_matrix((GeoTsMatrix)m[, (object)t=0[, (object)e=0[, (IntVector)v=[]]]]) → ARegionEnvironment :

Construct ARegionEnvironment from a specified slice of a GeoTsMatrix

Parameters:

• m (GeoTsMatrix) – The matrix from which to extract temperature,precipitation,radiation,wind-speed,rel-hum data

• t (int) – the forecast index to extract

• e (int) – the ensemble index to extract

Returns:

ARegionEnvironment. A ready to use region environment for interpolation

v (IntVector): variable indicies that in order of appearance selects temperature,precipitation,radiation,wind-speed,rel-hum.If empty/default, same as [0,1,2,3,4]

Return type:

ARegionEnvironment

static deserialize((ByteVector)blob) → ARegionEnvironment :

convert a blob, as returned by .serialize() into a ARegionEnvironment

property precipitation

precipitation sources

Type:

PrecipitationSourceVector

property radiation

radiation sources

Type:

RadiationSourceVector

property rel_hum

rel-hum sources

Type:

RelHumSourceVector

serialize((ARegionEnvironment)self) → ByteVector :

convert ARegionEnvironment into a binary blob that later can be restored with the .deserialize(blob) method

property temperature

temperature sources

Type:

TemperatureSourceVector

property variables

returns the list of available forcing variables as tuples(string,reference_to_variable)

property wind_speed

wind-speed sources

Type:

WindSpeedSourceVector

shyft.hydrology.ActualEvapotranspirationCalculate_step((object)water_level, (object)potential_evapotranspiration, (object)scale_factor, (object)snow_fraction, (time)dt) → float :

actual_evapotranspiration calculates actual evapotranspiration, returning same unit as input pot.evap based on supplied parameters

Parameters:

• () (dt) – [mm] water level eqvivalent in ground, ae goes to zero if ground is drying out

• () – [mm/x], x time-unit

• () – typically 1.5

• () – 0..1 there is to ae over snow surface, so snow_fraction 1.0, yields 0.0

• () – [s] timestep length, currently not part of the formula

Returns:

actual evapotranspiration.

class shyft.hydrology.ActualEvapotranspirationParameter

Bases: instance

__init__((ActualEvapotranspirationParameter)arg1) → None

__init__( (ActualEvapotranspirationParameter)arg1 [, (object)ae_scale_factor]) -> None :

a new object with specified parameters

property ae_scale_factor

typical value 1.5

Type:

float

class shyft.hydrology.ActualEvapotranspirationResponse

Bases: instance

__init__((ActualEvapotranspirationResponse)arg1) → None

property ae

actual evapotranspiration

Type:

float

class shyft.hydrology.BTKParameter

Bases: instance

BTKParameter class with time varying gradient based on day no

__init__((BTKParameter)arg1) → None

__init__( (BTKParameter)arg1, (object)temperature_gradient, (object)temperature_gradient_sd) -> None :

specifying default temp.grad(not used) and std.dev[C/100m]

__init__( (BTKParameter)arg1, (object)temperature_gradient, (object)temperature_gradient_sd, (object)sill, (object)nugget, (object)range, (object)zscale) -> None :

full specification of all parameters

nug((BTKParameter)arg1) → float :

Nugget magnitude,default=0.5

range((BTKParameter)arg1) → float :

Point where semivariogram flattens out,default=200000.0

sill((BTKParameter)arg1) → float :

Value of semivariogram at range default=25.0

temperature_gradient((BTKParameter)self, (UtcPeriod)p) → float :

return default temp.gradient based on day of year calculated for midst of utcperiod p

temperature_gradient_sd((BTKParameter)arg1) → float :

returns Prior standard deviation of temperature gradient in [C/m]

zscale((BTKParameter)arg1) → float :

Height scale used during distance computations,default=20.0

class shyft.hydrology.CatchmentPropertyType

Bases: enum

CELL_CHARGE = shyft.hydrology._api.CatchmentPropertyType.CELL_CHARGE

DISCHARGE = shyft.hydrology._api.CatchmentPropertyType.DISCHARGE

ROUTED_DISCHARGE = shyft.hydrology._api.CatchmentPropertyType.ROUTED_DISCHARGE

SNOW_COVERED_AREA = shyft.hydrology._api.CatchmentPropertyType.SNOW_COVERED_AREA

SNOW_WATER_EQUIVALENT = shyft.hydrology._api.CatchmentPropertyType.SNOW_WATER_EQUIVALENT

names = {'CELL_CHARGE': shyft.hydrology._api.CatchmentPropertyType.CELL_CHARGE, 'DISCHARGE': shyft.hydrology._api.CatchmentPropertyType.DISCHARGE, 'ROUTED_DISCHARGE': shyft.hydrology._api.CatchmentPropertyType.ROUTED_DISCHARGE, 'SNOW_COVERED_AREA': shyft.hydrology._api.CatchmentPropertyType.SNOW_COVERED_AREA, 'SNOW_WATER_EQUIVALENT': shyft.hydrology._api.CatchmentPropertyType.SNOW_WATER_EQUIVALENT}

values = {0: shyft.hydrology._api.CatchmentPropertyType.DISCHARGE, 1: shyft.hydrology._api.CatchmentPropertyType.SNOW_COVERED_AREA, 2: shyft.hydrology._api.CatchmentPropertyType.SNOW_WATER_EQUIVALENT, 3: shyft.hydrology._api.CatchmentPropertyType.ROUTED_DISCHARGE, 4: shyft.hydrology._api.CatchmentPropertyType.CELL_CHARGE}

class shyft.hydrology.CellEnvironment

Bases: instance

Contains all ts projected to a certain cell-model using interpolation step (if needed)

__init__((CellEnvironment)arg1) → None

has_nan_values((CellEnvironment)self) → bool :

scans all time-series for nan-values

Returns:

has_nan. true if any nan is encounted, otherwise false

Return type:

bool

init((CellEnvironment)self, (TimeAxisFixedDeltaT)ta) → None :

zero all series, set time-axis ta

property precipitation

precipitation

Type:

TsFixed

property radiation

radiation

Type:

TsFixed

property rel_hum

relhum

Type:

TsFixed

property temperature

temperature

Type:

TsFixed

property wind_speed

wind speed

Type:

TsFixed

class shyft.hydrology.CellStateId

Bases: instance

Unique cell pseudo identifier of a state

A lot of Shyft models can appear in different geometries and resolutions.In a few rare cases we would like to store the state of a model.This would be typical for example for hydrological new - year 1 - sept in Norway. To ensure that each cell - state have a unique identifier so that we never risk mixing state from different cells or different geometries, we create a pseudo unique id that helps identifying unique cell - states given this usage and context.

The primary usage is to identify which cell a specific identified state belongs to.

__init__((CellStateId)arg1) → None

__init__( (CellStateId)arg1, (object)cid, (object)x, (object)y, (object)area) -> None :

construct CellStateId with specified parameters

property area

area in [m^2]

Type:

int

property cid

catchment identifier

Type:

int

property x

x position in [m]

Type:

int

property y

y position in [m]

Type:

int

class shyft.hydrology.FlowAdjustResult

Bases: instance

The result type of region-model .adjust_state_to_target_flow(..) method

__init__((FlowAdjustResult)arg1) → None

property diagnostics

If tuning failed, the diagnostics of failure, zero length/empty if success

Type:

str

property q_0

The flow m3/s from selected catchments before tuning

Type:

float

property q_r

The obtaioned flow m3/s after tuning

Type:

float

class shyft.hydrology.GammaSnowCalculator

Bases: instance

__init__((GammaSnowCalculator)arg1) → None

step((GammaSnowCalculator)arg1, (GammaSnowState)state, (GammaSnowResponse)response, (time)t, (time)dt, (GammaSnowParameter)parameter, (object)temperature, (object)radiation, (object)precipitation, (object)wind_speed, (object)rel_hum, (object)forest_fraction, (object)altitude) → None :

Step the snow model forward from time t to t+dt, given state, parameters and input.

Updates the state and response upon return.

Parameters:

• state (GammaSnowState) – param state state of type S,in/out, ref template parameters

• response (GammaSnowResponse) – the response , out parameter.

• t (float) – ttemperature degC, considered constant over timestep dt

• dt (time) – length of time-step, seconds

• param (GammaSnowParameter) – response result of type R, output only, ref. template parameters

• radiation (float) – in W/m2, considered constant over timestep

• precipitation (float) – in mm/h

• wind_speed (float) – in m/s

• rel_hum (float) – range 0..1

• forest_fraction (float) – range 0..1, influences calculation of effective snow_cv

• altitude (float) – 0..x [m], influences calculation of effective_snow_cv

class shyft.hydrology.GammaSnowParameter

Bases: instance

__init__((GammaSnowParameter)arg1) → None

__init__( (GammaSnowParameter)arg1, (object)winter_end_day_of_year [, (object)initial_bare_ground_fraction [, (object)snow_cv [, (object)tx [, (object)wind_scale [, (object)wind_const [, (object)max_water [, (object)surface_magnitude [, (object)max_albedo [, (object)min_albedo [, (object)fast_albedo_decay_rate [, (object)slow_albedo_decay_rate [, (object)snowfall_reset_depth [, (object)glacier_albedo]]]]]]]]]]]]]) -> None :

specifying most of the parameters

property calculate_iso_pot_energy

Whether or not to calculate the potential energy flux,default=false

Type:

float

effective_snow_cv((GammaSnowParameter)self, (object)forest_fraction, (object)altitude) → float :

returns the effective snow cv, taking the forest_fraction and altitude into the equations using corresponding factors

property fast_albedo_decay_rate

Albedo decay rate during melt [days],default=5.0

Type:

float

property glacier_albedo

Glacier ice fixed albedo, default=0.4

Type:

float

property initial_bare_ground_fraction

Bare ground fraction at melt onset,default= 0.04

Type:

float

is_snow_season((GammaSnowParameter)self, (time)t) → bool :

returns true if specified t is within the snow season, e.g. sept.. winder_end_day_of_year

is_start_melt_season((GammaSnowParameter)self, (time)t[, (time)dt=0]) → bool :

true if specified interval t day of year is wind_end_day_of_year

property max_albedo

Maximum albedo value,default=0.9

Type:

float

property max_water

Maximum liquid water content,default=0.1

Type:

float

property min_albedo

Minimum albedo value,default=0.6

Type:

float

property n_winter_days

number of winter-days, default 221

Type:

int

property slow_albedo_decay_rate

Albedo decay rate in cold conditions [days],default=5.0

Type:

float

property snow_cv

Spatial coefficient variation of fresh snowfall, default= 0.4

Type:

float

property snow_cv_altitude_factor

default=0.0, [1/m] the effective snow_cv gets an additional value of altitude[m]* snow_cv_altitude_factor

Type:

float

property snow_cv_forest_factor

default=0.0, [ratio] the effective snow_cv gets an additional value of geo.forest_fraction()*snow_cv_forest_factor

Type:

float

property snowfall_reset_depth

Snowfall required to reset albedo [mm],default=5.0

Type:

float

property surface_magnitude

Surface layer magnitude,default=30.0

Type:

float

property tx

default= -0.5 [degC]

Type:

float

property wind_const

Intercept in turbulent wind function,default=1.0

Type:

float

property wind_scale

Slope in turbulent wind function default=2.0 [m/s]

Type:

float

property winter_end_day_of_year

Last day of accumulation season,default= 100

Type:

int

class shyft.hydrology.GammaSnowResponse

Bases: instance

The response(output) from gamma-snow for one time-step

__init__((GammaSnowResponse)arg1) → None

property outflow

Water out from the snow pack [mm/h]

Type:

float

property sca

Snow covered area [0..1]

Type:

float

property storage

Snow storage in [mm] over the area

Type:

float

class shyft.hydrology.GammaSnowState

Bases: instance

The state description of the GammaSnow routine

__init__((GammaSnowState)arg1) → None

__init__( (GammaSnowState)arg1 [, (object)albedo [, (object)lwc [, (object)surface_heat [, (object)alpha [, (object)sdc_melt_mean [, (object)acc_melt [, (object)iso_pot_energy [, (object)temp_swe]]]]]]]]) -> None :

Construct gamma snow state with supplied parameters

property acc_melt

acc_melt (Accumulated melt depth) [mm],default = 0.0

Type:

float

property albedo

albedo (Broadband snow reflectivity fraction),default = 0.4

Type:

float

property alpha

alpha (Dynamic shape state in the SDC),default = 1.26

Type:

float

property iso_pot_energy

iso_pot_energy (Accumulated energy assuming isothermal snow surface) [J/m2],default = 0.0

Type:

float

property lwc

lwc (liquid water content) [mm],default = 0.1

Type:

float

property sdc_melt_mean

sdc_melt_mean (Mean snow storage at melt onset) [mm],default = 0.0

Type:

float

property surface_heat

surface_heat (Snow surface cold content) [J/m2],default = 30000.0

Type:

float

property temp_swe

temp_swe (Depth of temporary new snow layer during spring) [mm],default = 0.0

Type:

float

class shyft.hydrology.GeoCellData

Bases: instance

Represents common constant geo_cell properties across several possible models and cell assemblies. The idea is that most of our algorithms uses one or more of these properties, so we provide a common aspect that keeps this together. Currently it keep these items: - mid-point geo_point, (x,y,z) (default 0) - TIN data - the area in m^2, (default 1000 x 1000 m^2) - land_type_fractions (unspecified=1) - catchment_id def (-1) - radiation_slope_factor def 0.9 - routing_info def(0,0.0), i.e. not routed and hydrological distance=0.0m

__init__((GeoCellData)arg1) → None

__init__( (GeoCellData)self, (GeoPoint)mid_point, (object)area, (object)catchment_id [, (object)radiation_slope_factor [, (LandTypeFractions)land_type_fractions [, (RoutingInfo)routing_info]]]) -> None :

Constructs a GeoCellData with all parameters specified

Args:

mid_point (GeoPoint): specifies the x,y,z mid-point of the cell-area

area (float): area in unit [m^2]

catchment_id (int): catchment-id that this cell is a part of

radiation_slope_factor (float): aspect dependent factor used to calculate the effective radiation for this cell,range 0.0..1.0

land_type_fractions (LandTypeFractions): specifies the fractions of glacier, forrest, lake and reservoirs for this cell

routing_info (RoutingInfo): Specifies the destination routing network-node and velocity for this cell

__init__( (GeoCellData)self, (GeoPoint)p1, (GeoPoint)p2, (GeoPoint)p3, (object)epsg_id, (object)catchment_id [, (LandTypeFractions)land_type_fractions [, (RoutingInfo)routing_info]]) -> None :

Constructs a TIN-based GeoCellData with all parameters specified, slope/aspect etc. is based on TIN

Args:

p1 (GeoPoint): specifies the first vertex in TIN

p2 (GeoPoint): specifies the second vertex in TIN

p3 (GeoPoint): specifies the third vertex in TIN

epsg_id (int): specifies the geo projection as epsg-id, used for projection from cartesian coord to long-lat algorithms that needs this(e.g. radiation, TIN-models)

catchment_id (int): catchment-id that this cell is a part of

land_type_fractions (LandTypeFractions): specifies the fractions of glacier, forrest, lake and reservoirs for this cell

routing_info (RoutingInfo): Specifies the destination routing network-node and velocity for this cell

area((GeoCellData)self) → float :

returns the effective area, as projected to the horisontal plane, in m^2

aspect((GeoCellData)self) → float :

returns aspect, deg

catchment_id((GeoCellData)self) → int :

returns the current catchment_id

property epsg_id

the epsg-id that should consistently identify the geo projection for all cells in a region model

Type:

int

land_type_fractions_info((GeoCellData)self) → LandTypeFractions :

land_type_fractions

mid_point((GeoCellData)self) → GeoPoint :

returns the mid_point

radiation_slope_factor((GeoCellData)self) → float :

radiation slope factor

property routing_info

routing information for the cell keep destination id and hydrological distance to destination

Type:

RoutingInfo

set_catchment_id((GeoCellData)self, (object)catchment_id) → None :

Set the catchment_id to specified value Note: Only use this method before a region-model is created

Parameters:

catchment_id (int) – Catchment-id for this cell

set_land_type_fractions((GeoCellData)self, (LandTypeFractions)ltf) → None :

set new LandTypeFractions

set_tin_data((GeoCellData)self, (GeoPointVector)vertexes) → None :

set TIN data from vector of vertexes

slope((GeoCellData)self) → float :

returns slope, deg

surface_area((GeoCellData)self) → float :

returns the real surface area in m^2

vertexes((GeoCellData)self) → GeoPointVector :

returns vector of tin vertexes

class shyft.hydrology.GeoCellDataVector

Bases: instance

A vector, list, of GeoCellData

__init__((GeoCellDataVector)arg1) → None

__init__( (GeoCellDataVector)arg1, (GeoCellDataVector)const_ref_v) -> None

append((GeoCellDataVector)arg1, (object)arg2) → None

static deserialize()

object deserialize(tuple args, dict kwds) :

deserialize from a binary to GeoCellDataVector

extend((GeoCellDataVector)arg1, (object)arg2) → None

serialize()

object serialize(tuple args, dict kwds) :

serialize to a binary byte vector

class shyft.hydrology.GeoPointSource

Bases: instance

GeoPointSource contains common properties, functions for the point sources in Shyft. Typically it contains a GeoPoint (3d position), plus a time-series

__init__((GeoPointSource)arg1) → None

__init__( (GeoPointSource)arg1, (GeoPoint)midpoint, (TimeSeries)ts) -> None

__init__( (GeoPointSource)arg1, (GeoTimeSeries)geo_ts) -> None

property geo_ts

returns a GeoTimeSeries where the geo-point are copied, but time-series are by-reference

Type:

GeoTimeSeries

mid_point((GeoPointSource)self) → GeoPoint :

returns a copy of mid_point

property mid_point_

reference to internal mid_point

property ts

time-series

Type:

TimeSeries

property uid

user specified identifier, string

Type:

str

class shyft.hydrology.GeoPointSourceVector

Bases: instance

__init__((GeoPointSourceVector)arg1) → None

__init__( (GeoPointSourceVector)arg1, (GeoPointSourceVector)src) -> None :

clone src

append((GeoPointSourceVector)arg1, (object)arg2) → None

extend((GeoPointSourceVector)arg1, (object)arg2) → None

values_at_time(t: int)

class shyft.hydrology.GlacierMeltParameter

Bases: instance

__init__((GlacierMeltParameter)arg1) → None

__init__( (GlacierMeltParameter)arg1, (object)dtf [, (object)direct_response=0.0]) -> None :

create parameter object with specified values

property direct_response

fraction that goes as direct response, (1-fraction) is routed through soil/kirchner routine,default=0.0

Type:

float

property dtf

degree timestep factor, default=6.0 [mm/day/degC]

Type:

float

class shyft.hydrology.HbvActualEvapotranspirationParameter

Bases: instance

__init__((HbvActualEvapotranspirationParameter)arg1) → None

__init__( (HbvActualEvapotranspirationParameter)arg1 [, (object)lp]) -> None :

a new object with specified parameters

property lp

typical value 150

Type:

float

class shyft.hydrology.HbvActualEvapotranspirationResponse

Bases: instance

__init__((HbvActualEvapotranspirationResponse)arg1) → None

property ae

ae value

Type:

float

shyft.hydrology.HbvActualEvapotranspirationCalculate_step((object)soil_moisture, (object)potential_evapotranspiration, (object)lp, (object)snow_fraction, (time)dt) → float :

actual_evapotranspiration calculates actual evapotranspiration, returning same unit as input pot.evap based on supplied parameters, formula like (1.0 - snow_fraction)*(soil_moisture < lp ? pot_evapo*(soil_moisture / lp):pot_evapo)

Parameters:

• () (dt) – [mm] water level eqvivalent in ground, ae goes to zero if ground is drying out

• () – [mm/x], x time-unit

• () – [mm] soil_moisture threshold, lp typically 150

• () – 0..1 there is to ae over snow surface, so snow_fraction 1.0, yields 0.0

• () – [s] timestep length, currently not part of the formula

Returns:

actual evapotranspiration.

class shyft.hydrology.HbvPhysicalSnowCalculator

Bases: instance

Generalized quantile based HBV Physical Snow model method

This algorithm uses arbitrary quartiles to model snow. No checks are performed to assert valid input. The starting points of the quantiles have to partition the unity, include the end points 0 and 1 and must be given in ascending order.

__init__((HbvPhysicalSnowCalculator)arg1, (HbvPhysicalSnowParameter)parameter) → None :

creates a calculator with given parameter and initial state, notice that state is updated in this call(hmm)

step((HbvPhysicalSnowCalculator)self, (HbvPhysicalSnowState)state, (HbvPhysicalSnowResponse)response, (time)t, (time)dt, (object)temperature, (object)rad, (object)prec_mm_h, (object)wind_speed, (object)rel_hum) → None :

steps the model forward from t to t+dt, updating state and response

class shyft.hydrology.HbvPhysicalSnowParameter

Bases: instance

__init__((HbvPhysicalSnowParameter)arg1) → None

__init__( (HbvPhysicalSnowParameter)arg1 [, (object)tx [, (object)lw [, (object)cfr [, (object)wind_scale [, (object)wind_const [, (object)surface_magnitude [, (object)max_albedo [, (object)min_albedo [, (object)fast_albedo_decay_rate [, (object)slow_albedo_decay_rate [, (object)snowfall_reset_depth [, (object)calculate_iso_pot_energy]]]]]]]]]]]]) -> None :

create parameter object with specifed values

__init__( (HbvPhysicalSnowParameter)arg1, (DoubleVector)snow_redist_factors, (DoubleVector)quantiles [, (object)tx [, (object)lw [, (object)cfr [, (object)wind_scale [, (object)wind_const [, (object)surface_magnitude [, (object)max_albedo [, (object)min_albedo [, (object)fast_albedo_decay_rate [, (object)slow_albedo_decay_rate [, (object)snowfall_reset_depth [, (object)calculate_iso_pot_energy]]]]]]]]]]]]) -> None :

create a parameter with snow re-distribution factors, quartiles and optionally the other parameters

property calculate_iso_pot_energy

whether or not to calculate the potential energy flux

Type:

float

property cfr

cfr

Type:

float

property fast_albedo_decay_rate

albedo decay rate during melt [days]

Type:

float

property intervals

snow quantiles list default 0, 0.25 0.5 1.0

Type:

DoubleVector

property lw

max liquid water content of the snow

Type:

float

property max_albedo

maximum albedo value

Type:

float

property min_albedo

minimum albedo value

Type:

float

property s

snow redistribution factors,default =1.0..

Type:

DoubleVector

set_snow_quantiles((HbvPhysicalSnowParameter)self, (DoubleVector)quantiles) → None

set_snow_redistribution_factors((HbvPhysicalSnowParameter)self, (DoubleVector)snow_redist_factors) → None

property slow_albedo_decay_rate

albedo decay rate in cold conditions [days]

Type:

float

property snowfall_reset_depth

snowfall required to reset albedo [mm]

Type:

float

property surface_magnitude

surface layer magnitude

Type:

float

property tx

threshold temperature determining if precipitation is rain or snow

Type:

float

property wind_const

intercept in turbulent wind function

Type:

float

property wind_scale

slope in turbulent wind function [m/s]

Type:

float

class shyft.hydrology.HbvPhysicalSnowResponse

Bases: instance

__init__((HbvPhysicalSnowResponse)arg1) → None

property hps_state

current state instance

Type:

HbvPhysicalSnowState

property outflow

from snow-routine in [mm]

Type:

float

property sca

snow-covered area

Type:

float

property storage

snow storage [mm]

Type:

float

class shyft.hydrology.HbvPhysicalSnowState

Bases: instance

__init__((HbvPhysicalSnowState)arg1) → None

__init__( (HbvPhysicalSnowState)arg1, (DoubleVector)albedo, (DoubleVector)iso_pot_energy [, (object)surface_heat [, (object)swe [, (object)sca]]]) -> None :

create a state with specified values

property albedo

albedo (Broadband snow reflectivity fraction)

Type:

float

distribute((HbvPhysicalSnowState)self, (HbvPhysicalSnowParameter)p[, (object)force=True]) → None :

Distribute state according to parameter settings.

Parameters:

• p (HbvPhysicalSnowParameter) – descr

• force (bool) – default true, if false then only distribute if state vectors are of different size than parameters passed

Returns:

.

Return type:

None

property iso_pot_energy

iso_pot_energy (Accumulated energy assuming isothermal snow surface) [J/m2]

Type:

float

property sca

snow covered area [0..1]

Type:

float

property sp

snow dry[mm]

Type:

DoubleVector

property surface_heat

surface_heat (Snow surface cold content) [J/m2]

Type:

float

property sw

snow water[mm]

Type:

DoubleVector

property swe

snow water equivalent[mm]

Type:

float

class shyft.hydrology.HbvSnowCalculator

Bases: instance

Generalized quantile based HBV Snow model method

This algorithm uses arbitrary quartiles to model snow. No checks are performed to assert valid input. The starting points of the quantiles have to partition the unity, include the end points 0 and 1 and must be given in ascending order.

__init__((HbvSnowCalculator)arg1, (HbvSnowParameter)parameter) → None :

creates a calculator with given parameter

step((HbvSnowCalculator)self, (HbvSnowState)state, (HbvSnowResponse)response, (time)t0, (time)t1, (object)precipitation, (object)temperature) → None :

steps the model forward from t0 to t1, updating state and response

class shyft.hydrology.HbvSnowParameter

Bases: instance

__init__((HbvSnowParameter)arg1) → None

__init__( (HbvSnowParameter)arg1, (object)tx [, (object)cx [, (object)ts [, (object)lw [, (object)cfr]]]]) -> None :

create parameter object with specifed values

__init__( (HbvSnowParameter)arg1, (DoubleVector)snow_redist_factors, (DoubleVector)quantiles [, (object)tx [, (object)cx [, (object)ts [, (object)lw [, (object)cfr]]]]]) -> None :

create a parameter with snow re-distribution factors, quartiles and optionally the other parameters

property cfr

cfr

Type:

float

property cx

temperature index, i.e., melt = cx(t - ts) in mm per degree C

Type:

float

property intervals

snow quantiles list default 0, 0.25 0.5 1.0

Type:

DoubleVector

property lw

max liquid water content of the snow

Type:

float

property s

snow redistribution factors,default =1.0..

Type:

DoubleVector

set_snow_quantiles((HbvSnowParameter)self, (DoubleVector)quantiles) → None

set_snow_redistribution_factors((HbvSnowParameter)self, (DoubleVector)snow_redist_factors) → None

property ts

threshold temperature for melt onset

Type:

float

property tx

threshold temperature determining if precipitation is rain or snow

Type:

float

class shyft.hydrology.HbvSnowResponse

Bases: instance

__init__((HbvSnowResponse)arg1) → None

property outflow

from snow-routine in [mm]

Type:

float

property snow_state

swe and snow covered area

Type:

HbvSnowState

class shyft.hydrology.HbvSnowState

Bases: instance

__init__((HbvSnowState)arg1) → None

__init__( (HbvSnowState)arg1, (object)swe [, (object)sca]) -> None :

create a state with specified values

distribute((HbvSnowState)self, (HbvSnowParameter)p[, (object)force=True]) → None :

Distribute state according to parameter settings.

Parameters:

• p (HbvSnowParameter) – descr

• force (bool) – default true, if false then only distribute if state vectors are of different size than parameters passed

Returns:

.

Return type:

None

property sca

snow covered area [0..1]

Type:

float

property sp

snow dry[mm]

Type:

DoubleVector

property sw

snow water[mm]

Type:

DoubleVector

property swe

snow water equivalent[mm]

Type:

float

class shyft.hydrology.HbvSoilCalculator

Bases: instance

Computing water through the soil moisture zone of the HBV model.

Reference:

• Nils Roar Sæhlthun: The Nordic HBV model 1996 https://publikasjoner.nve.no/publication/1996/publication1996_07.pdf

Notes

Lake and glacier are treated in the stack

__init__((HbvSoilCalculator)arg1, (HbvSoilParameter)parameter, (object)land_fraction) → None :

creates a calculator with given parameter

step((HbvSoilCalculator)self, (HbvSoilState)state, (HbvSoilResponse)response, (object)insoil, (object)pe, (object)sca) → None :

One step of the model, given state, parameters and input.

Updates the state and response.

Parameters:

• state (HbvSoilState) – param of type S, in/out, ref template parameters

• response (HbvSoilResponse) – param of type R, in/out, ref template parameters

• insoil (float) – inflow to soil

• pe (float) – potential evaporation

• sca (float) – the response , out parameter.

• land_fraction (float) – Land-fraction of the cell. Not directly used/desribed in ref. ‘Nils Roar’, but introduced here to adopt to the stack.

class shyft.hydrology.HbvSoilParameter

Bases: instance

__init__((HbvSoilParameter)arg1) → None

__init__( (HbvSoilParameter)arg1 [, (object)fc [, (object)beta]]) -> None :

create parameter object with specifed values

property beta

(unitless) exponent in the nonlinear relationship between soil moisture and field capacity. default=1.50738409

Type:

float

property fc

2000. maximum water content of the soil (Field Capacity), default=32.2755689

Type:

float

property infmax

(mm/h) maximum input rate to the soil moisture zone. Excess water will go directly to upper ground water zone. default=2.0

Type:

float

property lpdel

(unitless) dimensionless parameter (<1), from which level evapotranspiration is potential. Some publications use fcdel instead. default= 0.848557794

Type:

float

class shyft.hydrology.HbvSoilResponse

Bases: instance

__init__((HbvSoilResponse)arg1) → None

__init__( (HbvSoilResponse)arg1 [, (object)inuz [, (object)ae]]) -> None :

create response object with specifed values

property ae

(mm/h) Actual evapotranspiration. default=0

Type:

float

property inuz

(mm/h) Perculation to upper ground water zone. Called cuz by Nils Roar. default=0

Type:

float

class shyft.hydrology.HbvSoilState

Bases: instance

__init__((HbvSoilState)arg1) → None

__init__( (HbvSoilState)arg1 [, (object)sm]) -> None :

create a state with specified values

property sm

Soil moisture [mm]. default=10

Type:

float

class shyft.hydrology.HbvTankCalculator

Bases: instance

Computing water through the HBV ground water zone of the HBV model.

Reference:

• Nils Roar Sæhlthun: The Nordic HBV model 1996 https://publikasjoner.nve.no/publication/1996/publication1996_07.pdf

Notes

Lake and glacier are treated in the stack

__init__((HbvTankCalculator)arg1, (HbvTankParameter)parameter, (object)lake_fraction) → None :

creates a calculator with given parameters

step((HbvTankCalculator)self, (HbvTankState)state, (HbvTankResponse)response, (object)from_soil, (object)precip, (object)t2m) → None :

One step of the model, given state, parameters and input.

Updates the state and response.

Parameters:

• state (HbvSoilState) – param of type S, in/out, ref template parameters

• response (HbvSoilResponse) – param of type R, in/out, ref template parameters

• from_soil (float) – [mm/step] Inflow to upper zone (from soil moisture)

• precip (float) – [mm/step] Routed precipitation. Assumed that it is corrected for lake fraction already.

• t2m (float) – [deg C] Air-temperature at 2m (proxy for water temperature)

• lake_fraction (float) – [unitless] Lake-fraction of the cell. Not directly used/desribed in ref.’Nils Roar’, but introduced here to adopt to the stack.

class shyft.hydrology.HbvTankParameter

Bases: instance

__init__((HbvTankParameter)arg1) → None

__init__( (HbvTankParameter)arg1 [, (object)uz1 [, (object)uz2 [, (object)kuz0 [, (object)kuz1 [, (object)kuz2 [, (object)perc [, (object)klz [, (object)ce [, (object)cevpl]]]]]]]]]) -> None :

create parameter object with specifed values

property ce

[ mm/deg/day ] Evapotranspiration constant (degree-day-factor). default=0.17/24

Type:

float

property cevpl

[ unitless ], adjustment factor for potential evapotranspiration on lakes. default=1.1

Type:

float

property klz

[ 1/step ] Slow response coefficient lower ground water zone. default=0.05

Type:

float

property kuz0

[ 1/step ] Slow response coefficient upper ground water zone. default=0.05

Type:

float

property kuz1

[ 1/step ] Mid response coefficient upper ground water zone. default=0.1

Type:

float

property kuz2

[ 1/step ] Fast response coefficient upper ground water zone. default=0 (not active)

Type:

float

property perc

[ mm/step ] Perculation to lower ground water zone. default=0.6

Type:

float

property uz1

[ mm ] Mid-threshold for upper ground water zone. default=10

Type:

float

property uz2

[ mm ] High-threshold for upper ground water zone. default=50

Type:

float

class shyft.hydrology.HbvTankResponse

Bases: instance

__init__((HbvTankResponse)arg1) → None

__init__( (HbvTankResponse)arg1 [, (object)quz0 [, (object)quz1 [, (object)quz2 [, (object)qlz [, (object)elake [, (object)perculation]]]]]]) -> None :

create response object with specifed values

property elake

[ mm/step ] Evaporation from lake

Type:

float

property perculation

[ mm/step ] Effective perculation from upper to lower

Type:

float

property q

[mm/step] Total discharge from tank

Type:

float

property qlz

[mm/step] Total for lower zone

Type:

float

property quz

[mm/step] Total for upper zone

Type:

float

property quz0

[mm/step] Upper zone slow response

Type:

float

property quz1

[mm/step] Upper zone mid response

Type:

float

property quz2

[mm/step] Upper zone fast response

Type:

float

class shyft.hydrology.HbvTankState

Bases: instance

__init__((HbvTankState)arg1) → None

__init__( (HbvTankState)arg1 [, (object)uz [, (object)lz]]) -> None :

create a state with specified values

property lz

Lower ground water zone content [mm]

Type:

float

property uz

Upper ground water zone content [mm]

Type:

float

class shyft.hydrology.SnowTilesParameter

Bases: instance

__init__((SnowTilesParameter)arg1) → None

__init__( (SnowTilesParameter)arg1, (object)shape [, (object)tx [, (object)cx [, (object)ts [, (object)lwmax [, (object)cfr [, (DoubleVector)area_fractions]]]]]]) -> None

property area_fractions

area fractions of the individual tiles, unit (-), range per tile [0.01, 1], the sum of the elements in the vector must equal 1

Type:

DoubleVector

property cfr

refreeze coefficient, unit (-), range [0, 1]

Type:

float

property cx

degree-day melt factor, unit (mm/C/day), range [0, 30]

Type:

float

property lwmax

max liquid water content given as a fraction of ice in the snowpack, unit (-), range [0, 1]

Type:

float

property shape

shape parameter of the Gamma distribution defining the multiplication factors for snowfall, unit (-), range [0.1, inf]

Type:

float

property ts

threshold temperature for melt onset, unit (C), range [-4, 4]

Type:

float

property tx

threshold temperature determining precipitation phase, unit (C), range [-4, 4]

Type:

float

class shyft.hydrology.IDWParameter

Bases: instance

IDWParameter is a simple place-holder for IDW parameters used during interpolation process. The two most common is max_distance and max_members. Additionally it keep distance measure-factor, so that the IDW distance is computed as 1 over pow(euclid distance,distance_measure_factor). zscale is used to discriminate neighbors that are at different elevation than target point.

__init__((IDWParameter)arg1) → None

__init__( (IDWParameter)arg1, (object)max_members [, (object)max_distance [, (object)distance_measure_factor]]) -> None :

create IDW from supplied parameters

property distance_measure_factor

IDW distance is computed as 1 over pow(euclid distance,distance_measure_factor), default=2.0

Type:

float

property max_distance

[meter] only neighbours within max distance is used for each destination-cell,default= 200000.0

Type:

float

property max_members

maximum members,neighbors used to interpolate into a point,default=10

Type:

int

property zscale

Use to weight neighbors having same elevation, default=1.0

Type:

float

class shyft.hydrology.IDWPrecipitationParameter

Bases: IDWParameter

For precipitation,the scaling model needs the scale_factor. adjusted_precipitation = precipitation* (scale_factor)^(z-distance-in-meters/100.0) Ref to IDWParameter for the other parameters

__init__((IDWPrecipitationParameter)arg1) → None

__init__( (IDWPrecipitationParameter)arg1, (object)scale_factor [, (object)max_members [, (object)max_distance]]) -> None :

create IDW from supplied parameters

property scale_factor

ref. formula for adjusted_precipitation, default=1.02

Type:

float

class shyft.hydrology.IDWTemperatureParameter

Bases: IDWParameter

For temperature inverse distance, also provide default temperature gradient to be used when the gradient can not be computed, or is outside specified limits. if gradient_by_equation is set true, and number of points >3, the temperature gradient computer will try to use the 4 closest points and determine the 3d gradient including the vertical gradient. In scenarios with constant gradients(vertical/horizontal), this is accurate) If the number of valide nearby points is to few to do the full gradient equation, or the gradient_by_equation is set to False, then the two points with maximum vertical distance (required to be more than the minimum_z_distance) is used to compute the gradient. If all of the above fails, the default-gradient is used. Please note: Carefully selecting the maximum horizontal distances, and number of neighbors is required to get optimal results. In case of non-grid, or sparse-grid scenarios, you might consider setting the parameters to enforce default-gradient or you can also consider using the bayesian temperature krieging algorithm if there are few temperature sources

__init__((IDWTemperatureParameter)arg1) → None

__init__( (IDWTemperatureParameter)arg1, (object)default_gradient [, (object)max_members [, (object)max_distance [, (object)gradient_by_equation [, (object)minimum_z_distance [, (object)gradient_min [, (object)gradient_max]]]]]]) -> None :

construct IDW for temperature as specified by arguments

property default_temp_gradient

[degC/m], default=-0.006

Type:

float

property gradient_by_equation

if true, gradient is computed using 4 closest neighbors, solving equations to find 3D temperature gradients.

Type:

bool

property gradient_max

[degC/m] default +0.01, if computed gradient larger than this, the default-gradient is used instead

Type:

float

property gradient_min

[degC/m] default -0.01, if computed gradient less than this, the default-gradient is used instead

Type:

float

property minimum_z_distance

[m] default 50m, the minimum vertical distance requirement for two points to be used for gradient computation

Type:

float

class shyft.hydrology.InterpolationParameter

Bases: instance

The InterpolationParameter keep parameters needed to perform the interpolation steps, IDW,BTK etc It is used as parameter in the model.run_interpolation() method

__init__((InterpolationParameter)arg1) → None

__init__( (InterpolationParameter)arg1, (BTKParameter)temperature, (IDWPrecipitationParameter)precipitation, (IDWParameter)wind_speed, (IDWParameter)radiation, (IDWParameter)rel_hum) -> None :

using BTK for temperature

__init__( (InterpolationParameter)arg1, (IDWTemperatureParameter)temperature, (IDWPrecipitationParameter)precipitation, (IDWParameter)wind_speed, (IDWParameter)radiation, (IDWParameter)rel_hum) -> None :

using smart IDW for temperature, typically grid inputs

property precipitation

IDW parameters for precipitation

Type:

IDWPrecipitationParameter

property radiation

IDW parameters for radiation

Type:

IDWParameter

property rel_hum

IDW parameters for relative humidity

Type:

IDWParameter

property temperature

BTK for temperature (in case .use_idw_for_temperature is false)

Type:

BTKParameter

property temperature_idw

IDW for temperature(in case .use_idw_for_temperature is true)

Type:

IDWTemperatureParameter

property use_idw_for_temperature

if true, the IDW temperature is used instead of BTK, useful for grid-input scenarios

Type:

bool

property wind_speed

IDW parameters for wind_speed

Type:

IDWParameter

class shyft.hydrology.KalmanBiasPredictor

Bases: instance

A bias predictor using a daily pattern KalmanFilter for temperature (etc.) (tbd)

__init__((KalmanBiasPredictor)arg1) → None

__init__( (KalmanBiasPredictor)arg1) -> None :

Constructs a bias predictor with default filter, parameters and state

__init__( (KalmanBiasPredictor)arg1, (KalmanFilter)filter) -> None :

create a bias predictor with specified filter

__init__( (KalmanBiasPredictor)arg1, (KalmanFilter)filter, (KalmanState)state) -> None :

create a bias predictor with specified filter and initial state

compute_running_bias(fc_ts, obs_ts, time_axis)

compute the running bias timeseries, using one ‘merged’ - forecasts and one observation time - series.

Before each day - period, the bias - values are copied out to form a continuous bias prediction time-series.

Parameters:

• bp (KalmanBiasPredictor) – The bias predictor object it self

• fc_ts (TimeSeries) – a merged forecast ts with period covering the observation_ts and time_axis supplied

• obs_ts (TimeSeries) – the observation time-series

• time_axis (TimeAxis) – covering the period/timesteps to be updated e.g. yesterday, 3h resolution steps, according to the points in the filter

Returns:

bias_ts – computed running bias-ts

Return type:

TimeSeries(time_axis,bias_vector,POINT_AVERAGE)

static compute_running_bias_ts((KalmanBiasPredictor)bias_predictor, (TimeSeries)forecast_ts, (TimeSeries)observation_ts, (TimeAxis)time_axis) → TimeSeries :

compute the running bias timeseries, using one ‘merged’ - forecasts and one observation time - series.

Before each day - period, the bias - values are copied out to form a continuous bias prediction time-series.

Parameters:

• bias_predictor (KalmanBiasPredictor) – The bias predictor object it self

• forecast_ts (TimeSeries) – a merged forecast ts, with period covering the observation_ts and time_axis supplied

• observation_ts (TimeSeries) – the observation time-series

• time_axis (TimeAxis) – covering the period/timesteps to be updated, e.g. yesterday, 3h resolution steps, according to the points in the filter

Returns:

bias_ts. With ts( time_axis,bias_vector,POINT_AVERAGE), computed running bias-ts

Return type:

TimeSeries

property filter

kalman filter with parameters

Type:

KalmanFilter

property state

state of the predictor

Type:

KalmanState

update_with_forecast(fc_set, obs, time_axis)

Parameters:

• bp –

• fc_set (TemperatureSourceVector or TsVector) –

• obs (TimeSeries) –

• time_axis (TimeAxis) –

Return type:

nothing

static update_with_forecast_vector((KalmanBiasPredictor)bias_predictor, (TsVector)temperature_sources, (TimeSeries)observation_ts, (TimeAxis)time_axis) → None :

update the bias-predictor with forecasts and observation After the update, the state is updated with new kalman estimates for the bias, .state.x

Parameters:

• bias_predictor (KalmanBiasPredictor) – The bias predictor object it self

• temperature_sources (TsVector) – a set of forecasts, in the order oldest to the newest.With the periods covering parts of the observation_ts and time_axis supplied

• observation_ts (TimeSeries) – the observation time-series

• time_axis (TimeAxis) – covering the period/timesteps to be updated, e.g. yesterday, 3h resolution steps, according to the points in the filter

static update_with_geo_forecast((KalmanBiasPredictor)bias_predictor, (TemperatureSourceVector)temperature_sources, (TimeSeries)observation_ts, (TimeAxis)time_axis) → None :

update the bias-predictor with forecasts and observation After the update, the state is updated with new kalman estimates for the bias, .state.x

Parameters:

• bias_predictor (KalmanBiasPredictor) – The bias predictor object it self

• temperature_sources (TemperatureSourceVector) – ta set of forecasts, in the order oldest to the newest.Note that the geo part of source is not used in this context, only the tswith periods covering parts of the observation_ts and time_axis supplied

• observation_ts (Timeseries) – the observation time-series

• time_axis (TimeAxis) – covering the period/timesteps to be updated,e.g. yesterday, 3h resolution steps, according to the points in the filter

class shyft.hydrology.KalmanFilter

Bases: instance

Specialized kalman filter for temperature (e.g.:solar-driven bias patterns) The observation point(t, v) is folded on to corresponding period of the day(number of periods in a day is parameterized, typically 8). A simplified kalman filter algorithm using the forecast bias as the state - variable. Observed bias(fc - obs) is feed into the filter and establishes the kalman best predicted estimates(x) for the bias. This bias can then be used as a correction to forecast in the future to compensate for systematic forecast errors. Credits: Thanks to met.no for providing the original source for this algorithm.

See also

https://en.wikipedia.org/wiki/Kalman_filter

__init__((KalmanFilter)arg1) → None

__init__( (KalmanFilter)arg1) -> None :

Construct a filter with default KalmanParameter

__init__( (KalmanFilter)arg1, (KalmanParameter)p) -> None :

Construct a filter with the supplied parameter

create_initial_state((KalmanFilter)arg1) → KalmanState :

returns initial state, suitable for starting, using the filter parameters

property parameter

The KalmanParameter used by this filter

update((KalmanFilter)arg1, (object)observed_bias, (time)t, (KalmanState)state) → None :

update the with the observed_bias for a specific period starting at utctime t

Parameters:

• observed_bias (float) – nan if no observation is available otherwise obs - fc

• t (time) – utctime of the start of the observation period, this filter utilizes daily solar patterns, so time in day - cycle is the only important aspect.

• state (KalmanState) – contains the kalman state, that is updated by the function upon return

class shyft.hydrology.KalmanParameter

Bases: instance

Defines the parameters that is used to tune the kalman-filter algorithm for temperature type of signals

__init__((KalmanParameter)arg1) → None

__init__( (KalmanParameter)arg1 [, (object)n_daily_observations [, (object)hourly_correlation [, (object)covariance_init [, (object)std_error_bias_measurements [, (object)ratio_std_w_over_v]]]]]) -> None :

Constructs KalmanParameter with default or supplied values

__init__( (KalmanParameter)arg1, (KalmanParameter)const_ref) -> None :

clone the supplied KalmanParameter

property covariance_init

default=0.5, for the error covariance P matrix start-values

Type:

float

property hourly_correlation

default=0.93, correlation from one-hour to the next

Type:

float

property n_daily_observations

default = 8 each 24hour, every 3 hour

Type:

int

property ratio_std_w_over_v

default=0.06, st.dev W /st.dev V ratio

Type:

float

property std_error_bias_measurements

default=2.0, st.dev for the bias measurements

Type:

float

class shyft.hydrology.KalmanState

Bases: instance

keeps the state of the specialized kalman-filter: * x : vector[n=n_daily_observations] best estimate * k : vector[n], gain factors * P : matrix[nxn], covariance * W : noise[nxn]

property P

returns numpy array of kalman.state.P, the nxn covariance matrix

property W

returns numpy array of kalman.state.W, the nxn noise matrix

__init__((KalmanState)arg1) → None

__init__( (KalmanState)arg1, (object)n_daily_observations, (object)covariance_init, (object)hourly_correlation, (object)process_noise_init) -> None :

create a state based on supplied parameters

__init__( (KalmanState)arg1, (KalmanState)clone) -> None :

clone the supplied state

__init__( (KalmanState)arg1) -> None :

construct a default state

static get_P((KalmanState)state) → DoubleVector :

returns a copy of current kalman covariance matrix P

static get_W((KalmanState)state) → DoubleVector :

returns a copy of current kalman noise matrix W

static get_k((KalmanState)state) → DoubleVector :

returns a copy of current kalman gain k

static get_x((KalmanState)state) → DoubleVector :

returns a copy of current bias estimate x

property k

represents the current kalman gain factors, kalman.state.k

size((KalmanState)arg1) → int :

returns the size of the state, corresponding to n_daily_observations

property x

represents the current bias estimate, kalman.state.x

class shyft.hydrology.KirchnerCalculator

Bases: instance

Kirchner model for computing the discharge based on precipitation and evapotranspiration data.

This algorithm is based on the log transform of the ode formulation of the time change in discharge as a function of measured precipitation, evapo-transpiration and discharge, i.e. equation 19 in the publication Catchments as simple dynamic systems: Catchment characterization, rainfall-runoff modeling, and doing ‘hydrology backward’ by James W. Kirchner, published in Water Resources Research, vol. 45, W02429, doi: 10.1029/2008WR006912, 2009.

__init__((KirchnerCalculator)arg1, (KirchnerParameter)param) → None :

create a calculator using supplied parameter

__init__( (KirchnerCalculator)arg1, (object)abs_err, (object)rel_err, (KirchnerParameter)param) -> None :

create a calculator using supplied parameter, also specifying the ODE error parameters

step((KirchnerCalculator)self, (KirchnerState)state, (KirchnerResponse)response, (time)t0, (time)t1, (object)precipitation, (object)evapotranspiration) → None :

step Kirchner model forward from time t0 to time t1

note: If the supplied q (state) is less than min_q(0.00001, it represents mm water..), it is forced to min_q to ensure numerical stability

Parameters:

• state (KirchnerState) – current state, updated on return

• response (KirchnerResponse) – the response , out parameter.

• t0 (time) – start time

• t1 (time) – end time

• precipitation (float) – in mm/h

• evapotranspiration (float) – in mm/h

class shyft.hydrology.KirchnerParameter

Bases: instance

__init__((KirchnerParameter)arg1) → None

__init__( (KirchnerParameter)arg1, (object)c1 [, (object)c2 [, (object)c3]]) -> None :

creates parameter object according to parameters

property c1

default =2.439

Type:

float

property c2

default= 0.966

Type:

float

property c3

default = -0.10

Type:

float

class shyft.hydrology.KirchnerResponse

Bases: instance

__init__((KirchnerResponse)arg1) → None

property q_avg

average discharge over time-step in [mm/h]

Type:

float

class shyft.hydrology.KirchnerState

Bases: instance

__init__((KirchnerState)arg1) → None

__init__( (KirchnerState)arg1, (object)q) -> None :

create a state specifying initial content q

property q

state water ‘content’ in [mm/h], it defaults to 0.0001 mm, zero is not a reasonable valid value

Type:

float

class shyft.hydrology.LandTypeFractions

Bases: instance

LandTypeFractions are used to describe type of land, like glacier, lake, reservoir and forest. It is designed as a part of GeoCellData

__init__((LandTypeFractions)arg1) → None

__init__( (LandTypeFractions)arg1, (object)glacier, (object)lake, (object)reservoir, (object)forest, (object)unspecified) -> None :

construct LandTypeFraction specifying the area of each type

forest((LandTypeFractions)arg1) → float :

returns the forest part

glacier((LandTypeFractions)arg1) → float :

returns the glacier part

lake((LandTypeFractions)arg1) → float :

returns the lake part

reservoir((LandTypeFractions)arg1) → float :

returns the reservoir part

set_fractions((LandTypeFractions)self, (object)glacier, (object)lake, (object)reservoir, (object)forest) → None :

set the fractions explicit, each a value in range 0..1, sum should be 1.0

snow_storage((LandTypeFractions)self) → float :

returns the area where snow can build up, 1.0-lake-reservoir

unspecified((LandTypeFractions)arg1) → float :

returns the unspecified part

class shyft.hydrology.MethodStackParameter

Bases: instance

Contains the parameters for the method-stack, related to inter-method and routing behaviour

__init__((MethodStackParameter)arg1) → None

__init__( (MethodStackParameter)arg1, (MethodStackParameter)clone) -> None :

make a clone

property reservoir_direct_response_fraction

range 0..1, default 1.0, e.g. all precipitation on a reservoir goes to direct response - set to 0.0, then all precipitation is routed as pr. standard for the stack

Type:

float

class shyft.hydrology.OKCovarianceType

Bases: enum

EXPONENTIAL = shyft.hydrology._api.OKCovarianceType.EXPONENTIAL

GAUSSIAN = shyft.hydrology._api.OKCovarianceType.GAUSSIAN

names = {'EXPONENTIAL': shyft.hydrology._api.OKCovarianceType.EXPONENTIAL, 'GAUSSIAN': shyft.hydrology._api.OKCovarianceType.GAUSSIAN}

values = {0: shyft.hydrology._api.OKCovarianceType.GAUSSIAN, 1: shyft.hydrology._api.OKCovarianceType.EXPONENTIAL}

class shyft.hydrology.OKParameter

Bases: instance

Ordinary Kriging Parameter, keeps parameters that controls the ordinary kriging calculation

__init__((OKParameter)arg1) → None

__init__( (OKParameter)arg1 [, (object)c [, (object)a [, (OKCovarianceType)cov_type [, (object)z_scale]]]]) -> None

property a

the a-constant, range or distance, value in the covariance formula

Type:

float

property c

the c-constant, sill value in the covariance formula

Type:

float

property cov_type

covariance type EXPONENTIAL|GAUSSIAN to be used

Type:

OKCovarianceType

property z_scale

z_scale to be used for range|distance calculations

Type:

float

class shyft.hydrology.PenmanMonteithCalculator

Bases: instance

Evapotranspiration model, Penman-Monteith equation, PM reference

ASCE-EWRI The ASCE Standardized Reference Evapotranspiration Equation Environmental and
   * Water Resources Institute (EWRI) of the American Society of Civil Engineers Task Com- mittee on Standardization of
   * Reference Evapotranspiration Calculation, ASCE, Washington, DC, Environmental and Water Resources Institute (EWRI) of
   * the American Society of Civil Engineers Task Com- mittee on Standardization of Reference Evapotranspiration Calculation,
   * ASCE, Washington, DC, 2005

calculating reference evapotranspiration This function is plain and simple, taking albedo and turbidity into the constructor and provides function: reference_evapotranspiration; [mm/s] units.

__init__((PenmanMonteithCalculator)arg1, (PenmanMonteithParameter)param) → None :

create a calculator using supplied parameter

reference_evapotranspiration((PenmanMonteithCalculator)self, (PenmanMonteithResponse)response, (time)dt, (object)net_radiation, (object)tempmax, (object)tempmin, (object)rhumidity, (object)elevation, (object)windspeed) → None :

calculates reference evapotranspiration (standard or full based on full_model param), updating response

class shyft.hydrology.PenmanMonteithParameter

Bases: instance

__init__((PenmanMonteithParameter)arg1) → None

__init__( (PenmanMonteithParameter)arg1, (object)height_veg, (object)height_ws, (object)height_t, (object)rl, (object)full_model) -> None :

a new object with specified parameters

property full_model

boolean to specify if full penman-monteith required, set to false by default, so it is asce-ewri standard

Type:

bool

property height_t

typical value 2.0

Type:

float

property height_veg

grass 0.15

Type:

float

property height_ws

typical value 2.0

Type:

float

property rl

stomatal resistance, for full PM only, 140

Type:

float

class shyft.hydrology.PenmanMonteithResponse

Bases: instance

__init__((PenmanMonteithResponse)arg1) → None

property et_ref

Type:

float

property soil_heat

Type:

float

class shyft.hydrology.PrecipitationCorrectionCalculator

Bases: instance

Scales precipitation with the specified scale factor

__init__((PrecipitationCorrectionCalculator)arg1) → None

__init__( (PrecipitationCorrectionCalculator)arg1, (object)scale_factor) -> None :

create a calculator using supplied parameter

calc((PrecipitationCorrectionCalculator)arg1, (object)precipitation) → float :

returns scale_factor*precipitation

class shyft.hydrology.PrecipitationCorrectionParameter

Bases: instance

__init__((PrecipitationCorrectionParameter)arg1) → None

__init__( (PrecipitationCorrectionParameter)arg1, (object)scale_factor) -> None :

creates parameter object according to parameters

property scale_factor

default =1.0

Type:

float

class shyft.hydrology.PrecipitationSource

Bases: GeoPointSource

geo located precipitation[mm/h]

__init__((PrecipitationSource)arg1) → None

__init__( (PrecipitationSource)arg1, (GeoPoint)midpoint, (TimeSeries)ts) -> None

__init__( (PrecipitationSource)arg1, (GeoTimeSeries)geo_ts) -> None

vector_t

alias of PrecipitationSourceVector

class shyft.hydrology.PrecipitationSourceVector

Bases: instance

__init__((PrecipitationSourceVector)arg1) → None

__init__( (object)arg1, (list)geo_ts_list) -> object :

Construct from list

__init__( (object)arg1, (GeoTimeSeriesVector)geo_ts_vector) -> object :

Construct from a GeoTimeSeriesVector, Reference to the shyft.time_series.GeoTsMatrix.extract_geo_ts_vector() to see how to create one from the dtss/geo extensions

__init__( (PrecipitationSourceVector)arg1, (PrecipitationSourceVector)src) -> None :

clone src

append((PrecipitationSourceVector)arg1, (object)arg2) → None

extend((PrecipitationSourceVector)arg1, (object)arg2) → None

static from_geo_and_ts_vector((GeoPointVector)geo_points, (TsVector)tsv) → PrecipitationSourceVector :

Create from a geo_points and corresponding ts-vectors

Parameters:

geo_points (GeoPointVector) – the geo-points

Returns:

src_vector. a newly created geo-located vector of specified type

tsv (TsVector): the corresponding time-series located at corresponding geo-point

Return type:

SourceVector

property geo_tsvector

returns a GeoTimeSeriesVector containing GeoTimeSeries where the geo-points are copied, but time-series are by-reference

Type:

GeoTimeSeriesVector

values_at_time(t: int)

class shyft.hydrology.PriestleyTaylorCalculator

Bases: instance

PriestleyTaylor,PT, (google for PriestleyTaylor) primitive implementation for calculating the potential evaporation. This function is plain and simple, taking land_albedo and PT.alpha into the constructor and provides a function that calculates potential evapotransporation [mm/s] units.

__init__((PriestleyTaylorCalculator)arg1, (object)land_albedo, (object)alpha) → None

potential_evapotranspiration((PriestleyTaylorCalculator)arg1, (object)temperature, (object)global_radiation, (object)rhumidity) → float :

Calculate PotentialEvapotranspiration, given specified parameters

• param temperature in [degC]

• param global_radiation [W/m2]

• param rhumidity in interval [0,1]

• return PotentialEvapotranspiration in [mm/s] units

class shyft.hydrology.PriestleyTaylorParameter

Bases: instance

__init__((PriestleyTaylorParameter)arg1) → None

__init__( (PriestleyTaylorParameter)arg1 [, (object)albedo [, (object)alpha]]) -> None :

a new object with specified parameters

property albedo

typical value 0.2

Type:

float

property alpha

typical value 1.26

Type:

float

class shyft.hydrology.PriestleyTaylorResponse

Bases: instance

__init__((PriestleyTaylorResponse)arg1) → None

property pot_evapotranspiration

response

Type:

float

class shyft.hydrology.RadiationCalculator

Bases: instance

Radiation,R,

reference

Allen, R. G.; Trezza, R. & Tasumi, M. Analytical integrated functions for daily solar radiation on slopes Agricultural and Forest Meteorology, 2006, 139, 55-73)
primitive implementation for calculating predicted clear-sky short-wave solar radiation for inclined surfaces

This function is plain and simple, taking albedo and turbidity into the constructor and provides 2 functions:

• net_radiation calculates predicted solar radiation (if no measured data available) or translates measured data into the slope plus adds the longwave radiation: instantaneously;

• net_radiation_step calculates predicted solar radiation or/and translates measured horizontal radiation into sloped surface for the time period between tstart and tend plus adds the lw radiation

Recommended usage is the net_radiation_step for 24h-steps; it was also tested with 1h and 3h steps

__init__((RadiationCalculator)arg1, (RadiationParameter)param) → None :

create a calculator using supplied parameter

net_radiation((RadiationCalculator)self, (RadiationResponse)response, (object)latitude, (time)t1, (time)dt, (object)slope, (object)aspect, (object)temperature, (object)rhumidity, (object)elevation, (object)rsm) → None :

calculates net radiation using either step or instantaneous method, updating response

net_radiation_inst((RadiationCalculator)self, (RadiationResponse)response, (object)latitude, (time)t, (object)slope, (object)aspect, (object)temperature, (object)rhumidity, (object)elevation, (object)rsm) → None :

calculates net radiation using instantaneous method, updating response

net_radiation_step((RadiationCalculator)self, (RadiationResponse)response, (object)latitude, (time)t1, (time)dt, (object)slope, (object)aspect, (object)temperature, (object)rhumidity, (object)elevation, (object)rsm) → None :

calculates net radiation, updating response

net_radiation_step_asce_st((RadiationCalculator)self, (RadiationResponse)response, (object)latitude, (time)t1, (time)dt, (object)slope, (object)aspect, (object)temperature, (object)rhumidity, (object)elevation, (object)rsm) → None :

calculates net radiation, updating response

class shyft.hydrology.RadiationParameter

Bases: instance

__init__((RadiationParameter)arg1) → None

__init__( (RadiationParameter)arg1, (object)albedo, (object)turbidity) -> None :

a new object with specified parameters

property albedo

typical value 0.2

Type:

float

property turbidity

typical value 1.0

Type:

float

class shyft.hydrology.RadiationResponse

Bases: instance

__init__((RadiationResponse)arg1) → None

property net

Type:

float

property net_lw

Type:

float

property net_sw

Type:

float

property ra

Type:

float

property sw_cs_p

Type:

float

property sw_t

Type:

float

class shyft.hydrology.RadiationSource

Bases: GeoPointSource

geo located radiation[W/m2]

__init__((RadiationSource)arg1) → None

__init__( (RadiationSource)arg1, (GeoPoint)midpoint, (TimeSeries)ts) -> None

__init__( (RadiationSource)arg1, (GeoTimeSeries)geo_ts) -> None

vector_t

alias of RadiationSourceVector

class shyft.hydrology.RadiationSourceVector

Bases: instance

__init__((RadiationSourceVector)arg1) → None

__init__( (object)arg1, (list)geo_ts_list) -> object :

Construct from list

__init__( (object)arg1, (GeoTimeSeriesVector)geo_ts_vector) -> object :

Construct from a GeoTimeSeriesVector, Reference to the shyft.time_series.GeoTsMatrix.extract_geo_ts_vector() to see how to create one from the dtss/geo extensions

__init__( (RadiationSourceVector)arg1, (RadiationSourceVector)src) -> None :

clone src

append((RadiationSourceVector)arg1, (object)arg2) → None

extend((RadiationSourceVector)arg1, (object)arg2) → None

static from_geo_and_ts_vector((GeoPointVector)geo_points, (TsVector)tsv) → RadiationSourceVector :

Create from a geo_points and corresponding ts-vectors

Parameters:

geo_points (GeoPointVector) – the geo-points

Returns:

src_vector. a newly created geo-located vector of specified type

tsv (TsVector): the corresponding time-series located at corresponding geo-point

Return type:

SourceVector

property geo_tsvector

returns a GeoTimeSeriesVector containing GeoTimeSeries where the geo-points are copied, but time-series are by-reference

Type:

GeoTimeSeriesVector

values_at_time(t: int)

class shyft.hydrology.RelHumSource

Bases: GeoPointSource

geo located relative humidity[%rh], range 0..1

__init__((RelHumSource)arg1) → None

__init__( (RelHumSource)arg1, (GeoPoint)midpoint, (TimeSeries)ts) -> None

__init__( (RelHumSource)arg1, (GeoTimeSeries)geo_ts) -> None

vector_t

alias of RelHumSourceVector

class shyft.hydrology.RelHumSourceVector

Bases: instance

__init__((RelHumSourceVector)arg1) → None

__init__( (object)arg1, (list)geo_ts_list) -> object :

Construct from list

__init__( (object)arg1, (GeoTimeSeriesVector)geo_ts_vector) -> object :

Construct from a GeoTimeSeriesVector, Reference to the shyft.time_series.GeoTsMatrix.extract_geo_ts_vector() to see how to create one from the dtss/geo extensions

__init__( (RelHumSourceVector)arg1, (RelHumSourceVector)src) -> None :

clone src

append((RelHumSourceVector)arg1, (object)arg2) → None

extend((RelHumSourceVector)arg1, (object)arg2) → None

static from_geo_and_ts_vector((GeoPointVector)geo_points, (TsVector)tsv) → RelHumSourceVector :

Create from a geo_points and corresponding ts-vectors

Parameters:

geo_points (GeoPointVector) – the geo-points

Returns:

src_vector. a newly created geo-located vector of specified type

tsv (TsVector): the corresponding time-series located at corresponding geo-point

Return type:

SourceVector

property geo_tsvector

returns a GeoTimeSeriesVector containing GeoTimeSeries where the geo-points are copied, but time-series are by-reference

Type:

GeoTimeSeriesVector

values_at_time(t: int)

class shyft.hydrology.River

Bases: instance

A river that we use for routing, its a single piece of a RiverNetwork

The routing river have flow from:

1. zero or more ‘cell_nodes’, typically a cell_model type, lateral flow,like cell.rc.average_discharge [m3/s]

2. zero or more upstream connected rivers, taking their .output_m3s()

then a routing river can optionally be connected to a down-stream river providing a routing function (currently just a convolution of a uhg).

This definition is recursive, and we use RiverNetwork to ensure the routing graph is directed and with no cycles.

__init__((River)arg1) → None

__init__( (River)arg1, (object)id [, (RoutingInfo)downstream [, (UHGParameter)parameter]]) -> None :

a new object with specified parameters, notice that a valid river-id|routing-id must be >0

property downstream

routing information for downstream, target-id, and hydrological distance

Type:

RoutingInfo

property id

a valid identifier >0 for the river|routing element

Type:

int

property parameter

describing the downstream propagation

Type:

UHGParameter

uhg((River)self, (time)dt) → DoubleVector :

create the hydro-graph for this river, taking specified delta-t, dt, static hydrological distance as well as the shape parameters alpha and beta used to form the gamma-function. The length of the uhg (delay) is determined by the downstream-distance, and the velocity parameter. The shape of the uhg is determined by alpha&beta parameters.

class shyft.hydrology.RiverNetwork

Bases: instance

A RiverNetwork takes care of the routing see also description of River The RiverNetwork provides all needed functions to build routing into the region model It ensures safe manipulation of rivers:

• no cycles,

• no duplicate object-id’s etc.

__init__((RiverNetwork)arg1) → None

__init__( (RiverNetwork)arg1, (RiverNetwork)clone) -> None :

make a clone of river-network

add((RiverNetwork)self, (River)river) → RiverNetwork :

add a river to the network, verifies river id, no cycles etc.

raises exception on error tip: build your river-network from downstream to upstream order

downstream_by_id((RiverNetwork)self, (object)id) → int :

return id of downstream river, 0 if none

network_contains_directed_cycle((RiverNetwork)self) → bool :

True if network have cycles detected

remove_by_id((RiverNetwork)self, (object)id) → None :

disconnect and remove river for network

river_by_id((RiverNetwork)self, (object)id) → River :

get river by id

set_downstream_by_id((RiverNetwork)self, (object)id, (object)downstream_id) → None :

set downstream target for specified river id

upstreams_by_id((RiverNetwork)self, (object)id) → IntVector :

returns a list(vector) of id of upstream rivers from the specified one

class shyft.hydrology.RoutingInfo

Bases: instance

Describe the hydrological distance and the id of the target routing element (river)

__init__((RoutingInfo)arg1) → None

__init__( (RoutingInfo)arg1 [, (object)id [, (object)distance]]) -> None :

create an object with the supplied parameters

property distance

the hydrological distance, in unit of [m]

Type:

float

property id

id of the target,down-stream river

Type:

int

class shyft.hydrology.SkaugenCalculator

Bases: instance

Skaugen snow model method

This algorithm uses theory from Skaugen

__init__((SkaugenCalculator)arg1) → None

step((SkaugenCalculator)arg1, (time)delta_t, (SkaugenParameter)parameter, (object)temperature, (object)precipitation, (object)radiation, (object)wind_speed, (SkaugenState)state, (SkaugenResponse)response) → None :

steps the model forward delta_t seconds, using specified input, updating state and response

class shyft.hydrology.SkaugenParameter

Bases: instance

__init__((SkaugenParameter)arg1) → None

__init__( (SkaugenParameter)arg1, (object)alpha_0, (object)d_range, (object)unit_size, (object)max_water_fraction, (object)tx, (object)cx, (object)ts, (object)cfr) -> None :

create parameter object with specifed values

__init__( (SkaugenParameter)arg1, (SkaugenParameter)p) -> None :

create a clone of p

property alpha_0

default = 40.77

Type:

float

property cfr

default = 0.01

Type:

float

property cx

default = 2.5

Type:

float

property d_range

default = 113.0

Type:

float

property max_water_fraction

default = 0.1

Type:

float

property ts

default = 0.14

Type:

float

property tx

default = 0.16

Type:

float

property unit_size

default = 0.1

Type:

float

class shyft.hydrology.SkaugenResponse

Bases: instance

__init__((SkaugenResponse)arg1) → None

property outflow

from snow-routine in [mm/h] over cell-area

Type:

float

property sca

snow-covered area in fraction

Type:

float

property swe

snow water equivalient [mm] over cell-area

Type:

float

property total_stored_water

same as swe(deprecated)

Type:

float

class shyft.hydrology.SkaugenState

Bases: instance

__init__((SkaugenState)arg1) → None

__init__( (SkaugenState)arg1, (object)nu [, (object)alpha [, (object)sca [, (object)swe [, (object)free_water [, (object)residual [, (object)num_units]]]]]]) -> None :

create a state with specified values

__init__( (SkaugenState)arg1, (SkaugenState)s) -> None :

create a clone of s

property alpha

Type:

float

property free_water

Type:

float

property nu

Type:

float

property num_units

Type:

int

property residual

Type:

float

property sca

Type:

float

property swe

Type:

float

class shyft.hydrology.TargetSpecCalcType

Bases: enum

ABS_DIFF = shyft.hydrology._api.TargetSpecCalcType.ABS_DIFF

KLING_GUPTA = shyft.hydrology._api.TargetSpecCalcType.KLING_GUPTA

NASH_SUTCLIFFE = shyft.hydrology._api.TargetSpecCalcType.NASH_SUTCLIFFE

RMSE = shyft.hydrology._api.TargetSpecCalcType.RMSE

names = {'ABS_DIFF': shyft.hydrology._api.TargetSpecCalcType.ABS_DIFF, 'KLING_GUPTA': shyft.hydrology._api.TargetSpecCalcType.KLING_GUPTA, 'NASH_SUTCLIFFE': shyft.hydrology._api.TargetSpecCalcType.NASH_SUTCLIFFE, 'RMSE': shyft.hydrology._api.TargetSpecCalcType.RMSE}

values = {0: shyft.hydrology._api.TargetSpecCalcType.NASH_SUTCLIFFE, 1: shyft.hydrology._api.TargetSpecCalcType.KLING_GUPTA, 2: shyft.hydrology._api.TargetSpecCalcType.ABS_DIFF, 3: shyft.hydrology._api.TargetSpecCalcType.RMSE}

class shyft.hydrology.TargetSpecificationPts

Bases: instance

To guide the model calibration, we have a goal-function that we try to minimize This class contains the needed specification of this goal-function so that we can:

1. from simulations, collect time-series at catchment level for (DISCHARGE|SNOW_COVERED_AREA|SNOW_WATER_EQUIVALENT)

2. from observations, have a user-specified series the expression above should be equal to

3. use user specified kling-gupta factors to evaluate kind-of-difference between target and simulated

4. scale-factor to put a weight on this specific target-specification compared to other(we can have multiple)

5. a user specified id, uid, a string to identify the external source for calibration

__init__((object)arg1) → object :

Construct an empty class

__init__( (object)arg1, (TsFixed)ts, (IntVector)cids, (object)scale_factor, (TargetSpecCalcType)calc_mode, (object)s_r, (object)s_a, (object)s_b, (CatchmentPropertyType)catchment_property, (object)uid) -> object :

construct a target specification filled in with supplied parameters

Args:

ts (TsFixed): time-series containing the target time-series

cids (IntVector): A list of catchment id’s(cids) that together adds up into same as the target-ts

scale_factor (float): the weight of this target-specification

calc_mode (TargetSpecCalcType): specifies how to calculate the goal function, NS, KG, Abs,RMSE method

s_r (float): KG scalefactor for correlation

s_a (float): KG scalefactor for alpha(variance)

s_b (float): KG scalefactor for beta(bias)

catchment_property (CatchmentPropertyType): what to extract from catchment(DISCHARGE|SNOW_COVERED_AREA|SNOW_WATER_EQUIVALENT|ROUTED_DISCHARGE|CELL_CHARGE)

uid (str): user specified string/id to help integration efforts

__init__( (object)arg1, (TimeSeries)ts, (IntVector)cids, (object)scale_factor, (TargetSpecCalcType)calc_mode, (object)s_r, (object)s_a, (object)s_b, (CatchmentPropertyType)catchment_property, (object)uid) -> object :

construct a target specification filled in with supplied parameters

Args:

ts (TimeSeries): time-series containing the target time-series, note that the time-axis of this ts must be a fixed-interval type

cids (IntVector): A list of catchment id’s(cids) that together adds up into same as the target-ts

scale_factor (float): the weight of this target-specification

calc_mode (TargetSpecCalcType): specifies how to calculate the goal function, NS, KG, Abs method

s_r (float): KG scalefactor for correlation

s_a (float): KG scalefactor for alpha(variance)

s_b (float): KG scalefactor for beta(bias)

catchment_property (CatchmentPropertyType): what to extract from catchment(DISCHARGE|SNOW_COVERED_AREA|SNOW_WATER_EQUIVALENT|ROUTED_DISCHARGE|CELL_CHARGE)

uid (str): user specified string/id to help integration efforts

__init__( (object)arg1, (TsFixed)ts, (IntVector)cids, (object)scale_factor, (TargetSpecCalcType)calc_mode) -> object :

construct a target specification filled in with supplied parameters

Args:

ts (TsFixed): time-series containing the target time-series

cids (IntVector): A list of catchment id’s(cids) that together adds up into same as the target-ts

scale_factor (float): the weight of this target-specification

calc_mode (TargetSpecCalcType): specifies how to calculate the goal function, NS, KG, Abs method

__init__( (object)arg1, (TimeSeries)ts, (IntVector)cids, (object)scale_factor, (TargetSpecCalcType)calc_mode) -> object :

construct a target specification filled in with supplied parameters

Args:

ts (TimeSeries): time-series containing the target time-series, note the time-axis needs to be fixed_dt!

cids (IntVector): A list of catchment id’s(cids) that together adds up into same as the target-ts

scale_factor (float): the weight of this target-specification

calc_mode (TargetSpecCalcType): specifies how to calculate the goal function, NS, KG, Abs method

__init__( (object)arg1, (TsFixed)ts, (object)rid, (object)scale_factor, (TargetSpecCalcType)calc_mode, (object)s_r, (object)s_a, (object)s_b, (object)uid) -> object :

construct a target specification filled in with supplied parameters

Args:

ts (TsFixed): time-series containing the target time-series

rid (int): A river-id identifying the point of flow in the river-network

scale_factor (float): the weight of this target-specification

calc_mode (TargetSpecCalcType): specifies how to calculate the goal function, NS, KG, Abs method

s_r (float): KG scalefactor for correlation

s_a (float): KG scalefactor for alpha(variance)

s_b (float): KG scalefactor for beta(bias)

uid (str): user specified string/id to help integration efforts

__init__( (object)arg1, (TimeSeries)ts, (object)rid, (object)scale_factor, (TargetSpecCalcType)calc_mode, (object)s_r, (object)s_a, (object)s_b, (object)uid) -> object :

construct a target specification filled in with supplied parameters

Args:

ts (TimeSeries): time-series containing the target time-series, note time-axis required to be fixed-dt type

rid (int): A river-id identifying the point of flow in the river-network

scale_factor (float): the weight of this target-specification

calc_mode (TargetSpecCalcType): specifies how to calculate the goal function, NS, KG, Abs method

s_r (float): KG scalefactor for correlation

s_a (float): KG scalefactor for alpha(variance)

s_b (float): KG scalefactor for beta(bias)

uid (str): user specified string/id to help integration efforts

property calc_mode

NASH_SUTCLIFFE, KLING_GUPTA,ABS_DIFF,RMSE

Type:

TargetSpecCalcType

property catchment_indexes

catchment indexes, ‘cids’

Type:

IntVector

property catchment_property

DISCHARGE,SNOW_COVERED_AREA, SNOW_WATER_EQUIVALENT

Type:

CatchmentPropertyType

property river_id

river identifier for routed discharge calibration

Type:

int

property s_a

KG-scalefactor for alpha (variance)

Type:

float

property s_b

KG-scalefactor for beta (bias)

Type:

float

property s_r

KG-scalefactor for correlation

Type:

float

property scale_factor

the scale factor to be used when considering multiple target_specifications

Type:

float

property ts

target ts

Type:

TimeSeries

property uid

string

Type:

str

Type:

user specified identifier

class shyft.hydrology.TargetSpecificationVector

Bases: instance

A list of (weighted) target specifications to be used for model calibration

__init__((TargetSpecificationVector)arg1) → None

__init__( (TargetSpecificationVector)arg1, (TargetSpecificationVector)clone) -> None

append((TargetSpecificationVector)arg1, (object)arg2) → None

extend((TargetSpecificationVector)arg1, (object)arg2) → None

size()

class shyft.hydrology.TemperatureSource

Bases: GeoPointSource

geo located temperatures[deg Celcius]

__init__((TemperatureSource)arg1) → None

__init__( (TemperatureSource)arg1, (GeoPoint)midpoint, (TimeSeries)ts) -> None

__init__( (TemperatureSource)arg1, (GeoTimeSeries)geo_ts) -> None

vector_t

alias of TemperatureSourceVector

class shyft.hydrology.TemperatureSourceVector

Bases: instance

__init__((TemperatureSourceVector)arg1) → None

__init__( (object)arg1, (list)geo_ts_list) -> object :

Construct from list

__init__( (object)arg1, (GeoTimeSeriesVector)geo_ts_vector) -> object :

Construct from a GeoTimeSeriesVector, Reference to the shyft.time_series.GeoTsMatrix.extract_geo_ts_vector() to see how to create one from the dtss/geo extensions

__init__( (TemperatureSourceVector)arg1, (TemperatureSourceVector)src) -> None :

clone src

append((TemperatureSourceVector)arg1, (object)arg2) → None

extend((TemperatureSourceVector)arg1, (object)arg2) → None

static from_geo_and_ts_vector((GeoPointVector)geo_points, (TsVector)tsv) → TemperatureSourceVector :

Create from a geo_points and corresponding ts-vectors

Parameters:

geo_points (GeoPointVector) – the geo-points

Returns:

src_vector. a newly created geo-located vector of specified type

tsv (TsVector): the corresponding time-series located at corresponding geo-point

Return type:

SourceVector

property geo_tsvector

returns a GeoTimeSeriesVector containing GeoTimeSeries where the geo-points are copied, but time-series are by-reference

Type:

GeoTimeSeriesVector

values_at_time(t: int)

class shyft.hydrology.TsTransform

Bases: instance

transform the supplied time-series, f(t) interpreted according to its point_interpretation() policy into a new shyft core TsFixed time-series, that represents the true average for each of the n intervals of length dt, starting at start. the result ts will have the policy is set to POINT_AVERAGE_VALUE note: that the resulting ts is a fresh new ts, not connected to the source ts

__init__((TsTransform)arg1) → None

to_average((TsTransform)self, (time)start, (time)dt, (int)n, (TimeSeries)src) → TsFixed

to_average( (TsTransform)self, (time)start, (time)dt, (int)n, (TimeSeries)src) -> TsFixed

to_average( (TsTransform)self, (time)start, (time)dt, (int)n, (TsFixed)src) -> TsFixed

to_average( (TsTransform)self, (time)start, (time)dt, (int)n, (TsFixed)src) -> TsFixed

to_average( (TsTransform)self, (object)start, (object)dt, (int)n, (TimeSeries)src) -> TsFixed

to_average( (TsTransform)self, (object)start, (object)dt, (int)n, (TimeSeries)src) -> TsFixed

to_average( (TsTransform)self, (object)start, (object)dt, (int)n, (TsFixed)src) -> TsFixed

to_average( (TsTransform)self, (object)start, (object)dt, (int)n, (TsFixed)src) -> TsFixed

class shyft.hydrology.UHGParameter

Bases: instance

The Unit Hydro Graph Parameter contains sufficient description to create a unit hydro graph, that have a shape and a discretized ‘time-length’ according to the model time-step resolution. Currently we use a gamma function for the shape: <a ref=’https://en.wikipedia.org/wiki/Gamma_distribution’>gamma distribution</a>

__init__((UHGParameter)arg1) → None

__init__( (UHGParameter)arg1 [, (object)velocity [, (object)alpha [, (object)beta]]]) -> None :

a new object with specified parameters

property alpha

default 3.0,unit-less, ref. shape of gamma-function

Type:

float

property beta

default 0.0, unit-less, added to pdf of gamma(alpha,1.0)

Type:

float

property velocity

default 1.0, unit [m/s]

Type:

float

class shyft.hydrology.WindSpeedSource

Bases: GeoPointSource

geo located wind speeds[m/s]

__init__((WindSpeedSource)arg1) → None

__init__( (WindSpeedSource)arg1, (GeoPoint)midpoint, (TimeSeries)ts) -> None

__init__( (WindSpeedSource)arg1, (GeoTimeSeries)geo_ts) -> None

vector_t

alias of WindSpeedSourceVector

class shyft.hydrology.WindSpeedSourceVector

Bases: instance

__init__((WindSpeedSourceVector)arg1) → None

__init__( (object)arg1, (list)geo_ts_list) -> object :

Construct from list

__init__( (object)arg1, (GeoTimeSeriesVector)geo_ts_vector) -> object :

Construct from a GeoTimeSeriesVector, Reference to the shyft.time_series.GeoTsMatrix.extract_geo_ts_vector() to see how to create one from the dtss/geo extensions

__init__( (WindSpeedSourceVector)arg1, (WindSpeedSourceVector)src) -> None :

clone src

append((WindSpeedSourceVector)arg1, (object)arg2) → None

extend((WindSpeedSourceVector)arg1, (object)arg2) → None

static from_geo_and_ts_vector((GeoPointVector)geo_points, (TsVector)tsv) → WindSpeedSourceVector :

Create from a geo_points and corresponding ts-vectors

Parameters:

geo_points (GeoPointVector) – the geo-points

Returns:

src_vector. a newly created geo-located vector of specified type

tsv (TsVector): the corresponding time-series located at corresponding geo-point

Return type:

SourceVector

property geo_tsvector

returns a GeoTimeSeriesVector containing GeoTimeSeries where the geo-points are copied, but time-series are by-reference

Type:

GeoTimeSeriesVector

values_at_time(t: int)

shyft.hydrology.bayesian_kriging_temperature((TemperatureSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (BTKParameter)btk_parameter) → TemperatureSourceVector :

Runs kriging for temperature sources and project the temperatures out to the destination geo-timeseries

Notice that bayesian kriging is currently not very efficient for large grid inputs, using only one thread, and considering all source-timeseries (entire grid) for all destinations For few sources, spread out on a grid, it’s quite efficient should work well

Parameters:

• src (TemperatureSourceVector) – input a geo-located list of temperature time-series with filled in values (some might be nan etc.)

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis and they are transformed and interpolated into the destination-timeaxis

• btk_parameter (BTKParameter) – the parameters to be used during interpolation

Returns:

result. with filled in temperatures according to their position, the idw_parameters and time_axis

Return type:

TemperatureSourceVector

shyft.hydrology.compute_geo_ts_values_at_time((GeoPointSourceVector)geo_ts_vector, (time)t) → DoubleVector :

compute the ts-values of the GeoPointSourceVector for the specified time t and return DoubleVector

Args:

geo_ts_vector (GeoPointSourceVector): Any kind of GeoPointSource vector

Returns:

DoubleValue: values. List of extracted values at same size/position as the geo_ts_vector

t (int): timestamp in utc seconds since epoch

compute_geo_ts_values_at_time( (TemperatureSourceVector)geo_ts_vector, (time)t) -> DoubleVector :

compute the ts-values of the GeoPointSourceVector type for the specified time t and return DoubleVector

Args:

geo_ts_vector (GeoPointSourceVector): Any kind of GeoPointSource vector

Returns:

DoubleValue: values. List of extracted values at same size/position as the geo_ts_vector

t (int): timestamp in utc seconds since epoch

compute_geo_ts_values_at_time( (PrecipitationSourceVector)geo_ts_vector, (time)t) -> DoubleVector :

compute the ts-values of the GeoPointSourceVector type for the specified time t and return DoubleVector

Args:

geo_ts_vector (GeoPointSourceVector): Any kind of GeoPointSource vector

Returns:

DoubleValue: values. List of extracted values at same size/position as the geo_ts_vector

t (int): timestamp in utc seconds since epoch

compute_geo_ts_values_at_time( (WindSpeedSourceVector)geo_ts_vector, (time)t) -> DoubleVector :

compute the ts-values of the GeoPointSourceVector type for the specified time t and return DoubleVector

Args:

geo_ts_vector (GeoPointSourceVector): Any kind of GeoPointSource vector

Returns:

DoubleValue: values. List of extracted values at same size/position as the geo_ts_vector

t (int): timestamp in utc seconds since epoch

compute_geo_ts_values_at_time( (RelHumSourceVector)geo_ts_vector, (time)t) -> DoubleVector :

compute the ts-values of the GeoPointSourceVector type for the specified time t and return DoubleVector

Args:

geo_ts_vector (GeoPointSourceVector): Any kind of GeoPointSource vector

Returns:

DoubleValue: values. List of extracted values at same size/position as the geo_ts_vector

t (int): timestamp in utc seconds since epoch

compute_geo_ts_values_at_time( (RadiationSourceVector)geo_ts_vector, (time)t) -> DoubleVector :

compute the ts-values of the GeoPointSourceVector type for the specified time t and return DoubleVector

Args:

geo_ts_vector (GeoPointSourceVector): Any kind of GeoPointSource vector

Returns:

DoubleValue: values. List of extracted values at same size/position as the geo_ts_vector

t (int): timestamp in utc seconds since epoch

shyft.hydrology.create_precipitation_source_vector_from_np_array((TimeAxis)time_axis, (GeoPointVector)geo_points, (object)np_array, (point_interpretation_policy)point_fx) → PrecipitationSourceVector :

Create a PrecipitationSourceVector from specified time_axis,geo_points, 2-d np_array and point_fx.

Parameters:

• time_axis (TimeAxis) – time-axis that matches in length to 2nd dim of np_array

• geo_points (GeoPointVector) – the geo-positions for the time-series, should be of length n_ts

• np_array (np.ndarray) – numpy array of dtype=np.float64, and shape(n_ts,n_points)

• point_fx (point interpretation) – one of POINT_AVERAGE_VALUE|POINT_INSTANT_VALUE

Returns:

tsv. a PrecipitationSourceVector of length first np_array dim, n_ts, each with geo-point and time-series with time-axis, values and point_fx

Return type:

PrecipitationSourceVector

shyft.hydrology.create_radiation_source_vector_from_np_array((TimeAxis)time_axis, (GeoPointVector)geo_points, (object)np_array, (point_interpretation_policy)point_fx) → RadiationSourceVector :

Create a RadiationSourceVector from specified time_axis,geo_points, 2-d np_array and point_fx.

Parameters:

• time_axis (TimeAxis) – time-axis that matches in length to 2nd dim of np_array

• geo_points (GeoPointVector) – the geo-positions for the time-series, should be of length n_ts

• np_array (np.ndarray) – numpy array of dtype=np.float64, and shape(n_ts,n_points)

• point_fx (point interpretation) – one of POINT_AVERAGE_VALUE|POINT_INSTANT_VALUE

Returns:

tsv. a RadiationSourceVector of length first np_array dim, n_ts, each with geo-point and time-series with time-axis, values and point_fx

Return type:

RadiationSourceVector

shyft.hydrology.create_rel_hum_source_vector_from_np_array((TimeAxis)time_axis, (GeoPointVector)geo_points, (object)np_array, (point_interpretation_policy)point_fx) → RelHumSourceVector :

Create a RelHumSourceVector from specified time_axis,geo_points, 2-d np_array and point_fx.

Parameters:

• time_axis (TimeAxis) – time-axis that matches in length to 2nd dim of np_array

• geo_points (GeoPointVector) – the geo-positions for the time-series, should be of length n_ts

• np_array (np.ndarray) – numpy array of dtype=np.float64, and shape(n_ts,n_points)

• point_fx (point interpretation) – one of POINT_AVERAGE_VALUE|POINT_INSTANT_VALUE

Returns:

tsv. a RelHumSourceVector of length first np_array dim, n_ts, each with geo-point and time-series with time-axis, values and point_fx

Return type:

RelHumSourceVector

shyft.hydrology.create_temperature_source_vector_from_np_array((TimeAxis)time_axis, (GeoPointVector)geo_points, (object)np_array, (point_interpretation_policy)point_fx) → TemperatureSourceVector :

Create a TemperatureSourceVector from specified time_axis,geo_points, 2-d np_array and point_fx.

Parameters:

• time_axis (TimeAxis) – time-axis that matches in length to 2nd dim of np_array

• geo_points (GeoPointVector) – the geo-positions for the time-series, should be of length n_ts

• np_array (np.ndarray) – numpy array of dtype=np.float64, and shape(n_ts,n_points)

• point_fx (point interpretation) – one of POINT_AVERAGE_VALUE|POINT_INSTANT_VALUE

Returns:

tsv. a TemperatureSourceVector of length first np_array dim, n_ts, each with geo-point and time-series with time-axis, values and point_fx

Return type:

TemperatureSourceVector

shyft.hydrology.create_wind_speed_source_vector_from_np_array((TimeAxis)time_axis, (GeoPointVector)geo_points, (object)np_array, (point_interpretation_policy)point_fx) → WindSpeedSourceVector :

Create a WindSpeedSourceVector from specified time_axis,geo_points, 2-d np_array and point_fx.

Parameters:

• time_axis (TimeAxis) – time-axis that matches in length to 2nd dim of np_array

• geo_points (GeoPointVector) – the geo-positions for the time-series, should be of length n_ts

• np_array (np.ndarray) – numpy array of dtype=np.float64, and shape(n_ts,n_points)

• point_fx (point interpretation) – one of POINT_AVERAGE_VALUE|POINT_INSTANT_VALUE

Returns:

tsv. a WindSpeedSourceVector of length first np_array dim, n_ts, each with geo-point and time-series with time-axis, values and point_fx

Return type:

WindSpeedSourceVector

shyft.hydrology.glacier_melt_step((object)dtf, (object)temperature, (object)sca, (object)glacier_fraction) → float :

Calculates outflow from glacier melt rate [mm/h].

Parameters:

• dtf (float) – degree timestep factor [mm/day/deg.C]; lit. values for Norway: 5.5 - 6.4 in Hock, R. (2003), J. Hydrol., 282, 104-115.

• temperature (float) – degC, considered constant over timestep dt

• sca (float) – fraction of snow cover in cell [0..1], glacier melt occurs only if glacier fraction > snow fraction

• glacier_fraction (float) – glacier fraction [0..1] in the total area

Returns:

glacier_melt. output from glacier, melt rate [mm/h]

Return type:

float

shyft.hydrology.idw_precipitation((PrecipitationSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (IDWPrecipitationParameter)idw_param) → PrecipitationSourceVector :

Runs inverse distance interpolation to project precipitation sources out to the destination geo-timeseries

Parameters:

• src (PrecipitationSourceVector) – a geo-located list of precipitation time-series with filled in values (some might be nan etc.)

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis, they are transformed and interpolated into the destination-timeaxis

• idw_param (IDWPrecipitationParameter) – the parameters to be used during interpolation

Returns:

precipitation. with filled in precipitations according to their position, the idw_parameters and time_axis

Return type:

PrecipitationSourceVector

shyft.hydrology.idw_radiation((RadiationSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (IDWParameter)idw_param, (DoubleVector)slope_factors) → RadiationSourceVector :

Runs inverse distance interpolation to project radiation sources out to the destination geo-timeseries

Parameters:

• src (RadiationSourceVector) – input a geo-located list of precipitation time-series with filled in values (some might be nan etc.)

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis, they are transformed and interpolated into the destination-timeaxis

• idw_param (IDWParameter) – the parameters to be used during interpolation

• slope_factors (DoubleVector) – the slope-factor corresponding to geopoints, typical 0.9

Returns:

radiation. with filled in radiation according to their position, the idw_parameters and time_axis

Return type:

RadiationSourceVector

shyft.hydrology.idw_relative_humidity((RelHumSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (IDWParameter)idw_param) → RelHumSourceVector :

Runs inverse distance interpolation to project relative humidity sources out to the destination geo-timeseries

Parameters:

• src (RelHumSourceVector) – input a geo-located list of precipitation time-series with filled in values (some might be nan etc.)

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis, they are transformed and interpolated into the destination-timeaxis

• idw_param (IDWParameter) – the parameters to be used during interpolation

Returns:

relhum. with filled in relative humidity according to their position, the idw_parameters and time_axis

Return type:

RelHumSourceVector

shyft.hydrology.idw_temperature((TemperatureSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (IDWTemperatureParameter)idw_param) → TemperatureSourceVector :

Runs inverse distance interpolation to project temperature sources out to the destination geo-timeseries

Parameters:

• src (TemperatureSourceVectorn) – input a geo-located list of temperature time-series with filled in values (some might be nan etc.)

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis, they are transformed and interpolated into the destination-timeaxis

• idw_param (IDWTemperatureParameter) – the parameters to be used during interpolation, defines the behaviour of the interpolation. Please use help on the IDWTemperatureParameter for details.

Returns:

temperatures. with filled in temperatures according to their position, the idw_parameters and time_axis

Return type:

TemperatureSourceVector

shyft.hydrology.idw_wind_speed((WindSpeedSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (IDWParameter)idw_param[, (object)shear_factor=nan[, (object)hub_height=nan[, (object)reference_height=nan]]]) → WindSpeedSourceVector :

Runs inverse distance interpolation to project geo located wind input sources out to the destination geo-timeseries

Parameters:

• src (WindspeedSourceVector) – input a geo-located list of wind speed time-series with filled in values (some might be nan etc.)

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis, they are transformed and interpolated into the destination-timeaxis

• idw_param (IDWParametern) – the parameters to be used during interpolation

• shear_factor (float) – optional:wind shear coefficient to estimate the wind speed at higher elevations, typical 0.11 onshore and 0.15 offshore,>0.0

• hub_height (float) – optional:distance from the ground to the middle of the turbine’s rotor, >0.0

• reference_height (float) – optional: height above ground of measured wind speed, >0.0

Returns:

windspeed. with filled in wind speed according to their position, the idw_parameters and time_axis

Return type:

WindSpeedSourceVector

shyft.hydrology.make_uhg_from_gamma((object)n_steps, (object)alpha, (object)beta) → DoubleVector :

make_uhg_from_gamma a simple function to create a uhg (unit hydro graph) weight vector containing n_steps, given the gamma shape factor alpha and beta. ensuring the sum of the weight vector is 1.0 and that it has a min-size of one element (1.0)

Parameters:

• n_steps (int) – number of time-steps, elements, in the vectorn

• alpha (float) – the gamma_distribution gamma-factor

• beta (float) – the base-line, added to pdf(gamma(alpha,1))

Returns:

unit hydro graph factors. - normalized to sum 1.0

shyft.hydrology.ordinary_kriging((GeoPointSourceVector)src, (GeoPointVector)dst, (TimeAxisFixedDeltaT)time_axis, (OKParameter)parameter) → GeoPointSourceVector :

Runs ordinary kriging for geo sources and project the source out to the destination geo-timeseries Notice that kriging is currently not very efficient for large grid inputs, using only one thread, and considering all source-timeseries (entire grid) for all destinations For few sources, spread out on a grid, it’s quite efficient should work well Also note that this function currently does not elicite observations with nan-data most useful when you have control on the inputs, providing full set of data.

Parameters:

• src (GeoSourceVector) – input a geo-located list of time-series with filled in values

• dst (GeoPointVector) – the GeoPoints,(x,y,z) locations to interpolate into

• time_axis (TimeAxis) – the destination time-axis, recall that the inputs can be any-time-axis, and they are transformed and interpolated into the destination-timeaxis

• parameter (OKParameter) – the parameters to be used during interpolation

Returns:

result. with filled in ts-values according to their position, the parameters and time_axis

Return type:

GeoSourceVector

class shyft.hydrology.stat_scope

Bases: enum

Defines the scope of the indexes passed to statistics functions .cell : the indexes are considered as the i’th cell .catchment : the indexes are considered catchment identifiers

The statistics is then covering the cells that matches the selected criteria

catchment = shyft.hydrology._api.stat_scope.catchment

cell = shyft.hydrology._api.stat_scope.cell

names = {'catchment': shyft.hydrology._api.stat_scope.catchment, 'cell': shyft.hydrology._api.stat_scope.cell}

values = {0: shyft.hydrology._api.stat_scope.cell, 1: shyft.hydrology._api.stat_scope.catchment}

shyft.hydrology.version() → str :

C++ signature :

char const* version()

class shyft.hydrology.CalibrationOption

Bases: instance

The CalibrationOption controls how the calibration optmizer is run regarding method and termination criterias. Notice that the different optmizers do have variations in the termination criterias. All optimization algorithms expect at least one-dimensional paramteter space.

__init__((CalibrationOption)arg1) → None

__init__( (CalibrationOption)arg1, (OptimizerMethod)method [, (object)max_iterations [, (time)time_limit [, (object)solver_epsilon [, (object)x_epsilon [, (object)y_epsilon [, (object)tr_start [, (object)tr_stop]]]]]]]) -> None :

Initialises a ParameterOptimizer instance.

method (OptimizerMethod): select which parameter optimizer to use.

max_iterations (int): stop after this number of iterations (default 1500).

time_limit (float): GLOBAL: don’t run the global search longer than this (default 0, off).

solver_epsilon (float): GLOBAL: select which parameter optimizer to use (default 0.001).

x_epsilon (float): SCEUA: stop when normalized parameters x is within this range in variation.

y_epsilon (float): SCEUA: stop when goal function is stable within this range (not improving any further).

tr_start (float): BOBYQA: trust region start (default 0.1).

tr_stop (float): BOBYQA: trust region stop/end (default 1e-5).

static bobyqa((object)max_iterations, (object)tr_start, (object)tr_stop) → CalibrationOption :

Construct bobyqa options.

max_iterations (int): stop after this number of iterations (default 1500).

tr_start (float): BOBYQA: trust region start (default 0.1).

tr_stop (float): trust region stop/end (default 1e-5).

Returns:

co. An instance of CalibrationOption for the relevant optmization algorithm.

Return type:

CalibrationOption

static dream((object)max_iterations) → CalibrationOption :

Construct dream options

max_iterations (int): stop after this number of iterations (default 1500).

Returns:

co. An instance of CalibrationOption for the relevant optmization algorithm.

Return type:

CalibrationOption

static global_search((object)max_iterations, (time)time_limit, (object)solver_epsilon) → CalibrationOption :

Construct global search options

max_iterations (int): stop after this number of iterations (default 1500).

time_limit (float): don’t run the global search longer than this (default 0, off).

solver_epsilon (float): select which parameter optimizer to use (default 0.001).

Returns:

co. An instance of CalibrationOption for the relevant optmization algorithm.

Return type:

CalibrationOption

property max_iterations

stop after this number of iterations (default 1500)

Type:

int

property method

OptimizerMethod, which parameter optimizer to use

Type:

int

static sceua((object)max_iterations, (object)x_epsilon, (object)y_epsilon) → CalibrationOption :

Construct sceua options

max_iterations (int): stop after this number of iterations (default 1500).

x_epsilon (float): stop when normalized parameters x is within this range in variation.

y_epsilon (float): stop when goal function is stable within this range (not improving any further).

Returns:

co. An instance of CalibrationOption for the relevant optmization algorithm.

Return type:

CalibrationOption

property solver_epsilon

select which parameter optimizer to use (default 0.001)

Type:

float

Type:

GLOBAL

property time_limit

don’t run the global search longer than this (default 0, off)

Type:

time

Type:

GLOBAL

property tr_start

trust region start (default 0.1)

Type:

float

Type:

BOBYQA

property tr_stop

trust region stop/end (default 1e-5)

Type:

float

Type:

BOBYQA

property x_epsilon

stop when normalized parameters x is within this range in variation

Type:

float

Type:

SCEUA

property y_epsilon

stop when goal function is stable within this range (not improving any further)

Type:

float

Type:

SCEUA

class shyft.hydrology.OptimizerMethod

Bases: enum

Shyft calibration allow the user to select between one of these parameter optimizer methods.

BOBYQA = shyft.hydrology._api.OptimizerMethod.BOBYQA

DREAM = shyft.hydrology._api.OptimizerMethod.DREAM

GLOBAL = shyft.hydrology._api.OptimizerMethod.GLOBAL

SCEUA = shyft.hydrology._api.OptimizerMethod.SCEUA

names = {'BOBYQA': shyft.hydrology._api.OptimizerMethod.BOBYQA, 'DREAM': shyft.hydrology._api.OptimizerMethod.DREAM, 'GLOBAL': shyft.hydrology._api.OptimizerMethod.GLOBAL, 'SCEUA': shyft.hydrology._api.OptimizerMethod.SCEUA}

values = {0: shyft.hydrology._api.OptimizerMethod.BOBYQA, 1: shyft.hydrology._api.OptimizerMethod.GLOBAL, 2: shyft.hydrology._api.OptimizerMethod.DREAM, 3: shyft.hydrology._api.OptimizerMethod.SCEUA}

class shyft.hydrology.CalibrationStatus

Bases: instance

The CalibrationStatus is returned from drms, or local call to the region model calibration object.It provides status, progress, and current trace of parameters and goal function values

__init__()

Raises an exception This class cannot be instantiated from Python

result()

object result(tuple args, dict kwds) :

returns resulting calibrated parameter if available

property running

True if the calibration is still running

Type:

bool

trace_goal_function_value((CalibrationStatus)self, (object)i) → float :

returns the i’th goal function value

property trace_goal_function_values

goal function values obtained so far

Type:

DoubleVector

trace_parameter()

object trace_parameter(tuple args, dict kwds) :

returns the i’th parameter tried, corresponding to the i’th trace_goal_function value

property trace_size

returns the size of the parameter-trace

See also

trace_goal_function_value,trace_parameter

Type:

int

class shyft.hydrology.ParameterOptimizer

Bases: instance

The ParameterOptimizer allows for testing and comparing optimizer methods for the same inital parameters and goal function.

__init__((ParameterOptimizer)arg1, (DoubleVector)p_min, (DoubleVector)p_max, (object)fx) → None :

Initialises a ParameterOptimizer instance.

p_min (Union[DoubleVector[float], DoubleVector[int]]): the lower parameter bound in at least one-dimensional space.

p_max (Union[DoubleVector[float], DoubleVector[int]]): the upper parameter bound in at least one-dimensional space.

fx (Callable): the goal function to be used in the parameter optimization problem.

property fx

goal function for which parameters are optimized

Type:

Callable[[],float]

goal_function((ParameterOptimizer)self, (DoubleVector)x) → float :

The goal function to be used in the optimization problem.

x (Union[DoubleVector[float], DoubleVector[int]]): the point in at least one-dimensional space at which the goal function is evaluated.

Returns:

25. The function value f(x) at point x.

Return type:

DoubleVector[float]

optimize((ParameterOptimizer)self, (DoubleVector)x, (CalibrationOption)calibration_option) → DoubleVector :

Run the optimizer for given parameters and configuration.

x (Union[DoubleVector[float], DoubleVector[int]]): the initial point in at least one-dimensional space for the optimization problem.

calibration_option (CalibrationOption): the calibration for the various optimization methods.

Returns:

x_opt. The optimal parameters for which the optimum of f(x) is found.

Return type:

DoubleVector[float]

See also

CalibrationOption

property p_max

upper parameter bound in at least one-dimensional space

Type:

DoubleVector

property p_min

lower parameter bound in at least one-dimensional space

Type:

DoubleVector

class shyft.hydrology.DrmClient

Bases: instance

Distributed region model client provides all needed functionality to transfer Shyft region-models, and then run simulations/optimizations

__init__((DrmClient)self, (object)host_port, (object)timeout_ms) → None :

Creates a client with supplied arguments

adjust_q((DrmClient)self, (object)mid, (IntVector)indexes, (object)wanted_q[, (int)start_step=0[, (object)scale_range=3.0[, (object)scale_eps=0.001[, (int)max_iter=300[, (int)n_steps=1]]]]]) → FlowAdjustResult :

State adjustment to achieve wanted/observed flow

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – cell ids that should be adjusted

• wanted_q (float) – the average flow first time-step we want to achieve, in m**3/s

• start_step (int) – time-axis start step index, default=0

• scale_range (float) – default=3, min,max= scale0/scale_range.. scale0*scale_range

• scale_eps (float) – default 1e-3, stop iteration when scale-change is less than this

• max_iter (int) – default=300, stop searching for solution after this limit is reached

• n_steps (int) – default=1, number of steps on time-axis to average to match wanted flow

Returns:

. obtained flow in m**3/s. This can deviate from wanted flow due to model and state constraints. q_r is optimized q and q_0 is unadjusted.

Return type:

q_adjust_result

cancel_calibration((DrmClient)self, (object)mid) → bool :

Cancels any ongoing not finished calibration for the specified model

Parameters:

mid (str) – model identifier

Returns:

. indicating success

Return type:

bool

check_calibration((DrmClient)self, (object)mid) → CalibrationStatus :

Check ongoing calibration, return intermediate status with trace, or final status with trace and resulting parameters

Parameters:

() (mid) – model identifier

Returns:

. Calibration Status class with information and results

clone_model((DrmClient)self, (object)mid, (object)new_mid) → bool :

clone the specified model

Parameters:

• mid (str) – original model

• new_mid (str) – the model-id for the cloned model

Returns:

. true if succeeded

Return type:

bool

close((DrmClient)self) → None :

Close the connection. It will automatically reopen if needed.

copy_model((DrmClient)self, (object)mid, (object)new_mid) → bool :

full copy of the specified model

Parameters:

• mid (str) – original model

• new_mid (str) – the model-id for the copied model

Returns:

. true if succeeded

Return type:

bool

create_model((DrmClient)self, (object)mid, (RegionModelType)mtype, (GeoCellDataVector)gcd) → bool :

create the model

Parameters:

• mid (str) – model identifier

• mtype (enum rmodel_type) – rmodel_type.pt_gs_k rmodel_type.pt_gs_k_opt or similar model type

• gcd (GeoCellDataVector) – strongly typed list of GeoCellData

Returns:

. true if succeeded

Return type:

bool

fx((DrmClient)self, (object)mid, (object)fx_args) → bool :

Invoke the serverside fx callback, on the exlusively locked model given by mid

Parameters:

• mid (str) – model identifier

• fx_args (str) – args to the callback, typically a json string

Returns:

. the server side evaluation result, as pr. callback return value

Return type:

bool

get_catchment_parameter()

object get_catchment_parameter(tuple args, dict kwds) :

Get the effective catchment parameter for the specified catchment

Args:

mid (str): model identifier

cid (int): catchment identifier

Returns:

XXXParameter: . The catchment parameter for specified catchment

get_charge((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the charge

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_description((DrmClient)self, (object)mid) → str :

returns the user specified description string, typically a json formatted string.

Parameters:

mid (str) – model identifier

Returns:

. The description(json string) for the specified model

Return type:

str

get_discharge((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the discharge

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_geo_cell_data((DrmClient)self, (object)mid) → GeoCellDataVector :

returns the geo cell data vector for the specified model.

Parameters:

mid (str) – model identifier

Returns:

. The GeoCellDataVector for the specified model

Return type:

GeoCellDataVector

get_interpolation_parameter((DrmClient)self, (object)mid) → InterpolationParameter :

returns the current interpolation parameters used to interpolate region-env to the cells.

Parameters:

mid (str) – model identifier

Returns:

. The interpolation parameter for the specified model

Return type:

InterpolationParameter

get_model_ids((DrmClient)self) → StringVector :

returns a list of model ids (mids) that is alive and known at the remote server

Returns:

. Strongly typed list of strings naming the available models on the drms

Return type:

StringList

get_precipitation((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the precipitation

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_radiation((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the radiation

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_region_env((DrmClient)self, (object)mid) → ARegionEnvironment :

returns the current region-env for the specified model.

Parameters:

mid (str) – model identifier

Returns:

. The region envirionment for the specified model

Return type:

ARegionEnvironment

get_region_parameter()

object get_region_parameter(tuple args, dict kwds) :

Get the region model parameter settings

Args:

mid (str): model identifier

Returns:

XXXParameter: . The region parameter for the model

get_rel_hum((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the rel_hum

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_server_version((DrmClient)arg1) → str :

returns the server version

Returns:

version. Server version string

Return type:

str

get_snow_sca((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the snow_sca

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_snow_swe((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the snow_swe

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_state()

object get_state(tuple args, dict kwds) :

Extract cell state for the optionaly specified catchment ids, cids

Args:

mid (str): model identifier

indexes (IntVector): list of catchment-id’s, if empty, extract all

Returns:

xStateWithIdVector: . strongly typed list of stack state with identifier for the cells

get_temperature((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the temperature

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

get_time_axis((DrmClient)self, (object)mid) → TimeAxis :

Get the current time-axis of the model

Parameters:

mid (str) – model identifier

Returns:

. The region model time-axis

Return type:

TimeAxis

get_wind_speed((DrmClient)self, (object)mid, (IntVector)indexes[, (stat_scope)index_type=shyft.hydrology._api.stat_scope.catchment]) → TimeSeries :

get the wind speed

Parameters:

• mid (str) – model identifier

• indexes (List[int]) – indexes to be retrieved, the index_type tells if it’s cells or catchment indexes

• index_type (stat_scope) – stat_scope.(cell|catchment) denotes the type of indexes passed. cell returns sum of cell indexes, catchment returns sum of catchments

Returns:

. returns sum for catcment_ids

Return type:

TimeSeries

has_catchment_parameter((DrmClient)self, (object)mid, (int)cid) → bool :

Get the current time-axis of the model

Parameters:

• mid (str) – model identifier

• cid (int) – catchment identifier

Returns:

. True if catchment has its own parameter setting

Return type:

bool

property host_port

Endpoint network address of the remote server.

Type:

str

is_calculated((DrmClient)self, (object)mid, (int)catchment_id) → bool :

using the catchment_calculation_filter to decide if discharge etc. are calculated.

Parameters:

• mid (str) – model identifier

• cid (int) – catchment id

Returns:

. true if catchment id is calculated during runs

Return type:

bool

is_cell_env_ts_ok((DrmClient)self, (object)mid) → bool :

check if all values in cell.env_ts for selected calculation-filter is non-nan, i.e. valid numbers

Parameters:

mid (str) – model identifier

Returns:

. true if ok, false if not ok

Return type:

bool

property is_open

If the connection to the remote server is (still) open.

Type:

bool

property reconnect_count

Number of reconnects to the remote server that have been performed.

Type:

int

remove_catchment_parameter((DrmClient)self, (object)mid, (int)cid) → None :

Remove the specified catchments local parameter, and set it to the region parameter

Parameters:

• mid (str) – model identifier

• cid (int) – catchment identifier

remove_model((DrmClient)self, (object)mid) → bool :

remove the specified model

Parameters:

mid (str) – model identifier

Returns:

. true if succeeded

Return type:

bool

rename_model((DrmClient)self, (object)mid, (object)new_mid) → bool :

rename the specified model

Parameters:

• mid (str) – model identifier

• new_mid (str) – the new wanted model-id for the model

Returns:

. true if succeeded

Return type:

bool

revert_to_initial_state((DrmClient)self, (object)mid) → bool :

revert model to initial state, notice that this require that the set_current_state_as_initial_state() or run_cells() is called. The latter will set initial state if not already done.

Parameters:

mid (str) – model identifier

Returns:

. true if succeeded

Return type:

bool

run_cells((DrmClient)self, (object)mid[, (int)use_ncore=0[, (object)start_step=0[, (object)n_steps=0]]]) → bool :

Run calculation over the specified time axis. Requires that cells and environment have been initialized and interpolated.

Parameters:

• mid (str) – model identifier

• use_ncore (int) – default 0, means autodetect core, otherwise you can specify 1..n

• start_step (int) – default 0, from start step of time-axis

• n_steps (int) – default 0, means run entire time-axis, 1..n means number of steps from start_step

Returns:

. true if succeeded

Return type:

bool

run_interpolation((DrmClient)self, (object)mid, (InterpolationParameter)ip_parameter, (TimeAxis)ta, (ARegionEnvironment)r_env, (object)best_effort) → bool :

initializes the cell environment and project region environment time_series to cells.

Parameters:

• mid (str) – model identifier

• ip_parameter (InterpolationParameter) – interpolation parameter

• ta (TimeAxis) – time axis

• r_env (ARegionEnvironment) – region environment containing all geo-located sources

• best_effort (bool) – best effort type interpolation

Returns:

. true if succeeded

Return type:

bool

set_catchment_calculation_filter((DrmClient)self, (object)mid, (IntVector)catchment_id_list) → bool :

set catchment calculation filter

Parameters:

• mid (str) – model identifier

• catchment_id_list (List[int]) – list of catchment indexes

Returns:

. true if succeeded

Return type:

bool

set_catchment_parameter((DrmClient)self, (object)mid, (object)parameter, (int)cid) → bool :

set catchment parameter

Parameters:

• mid (str) – model identifier

• parameter (XXXXParameter) – strongly typed method stack parameter

• cid (int) – catchment id that should get the supplied parameter

Returns:

. true if succeeded

Return type:

bool

set_cell_environment((DrmClient)self, (object)mid, (TimeAxis)ta, (ARegionEnvironment)r_env) → bool :

Set the forcing data cell enviroment (cell.env_ts.* )

The method initializes the cell environment, that keeps temperature, precipitation etc for all the cells. The region-model time-axis is set to the supplied time-axis, so that the the region model is ready to run cells, using this time-axis.

There are strict requirements to the content of the region_env parameter:

• rm.cells[i].mid_point()== region_env.temperature[i].mid_point() for all i

• similar for precipitation,rel_hum,radiation,wind_speed

So same number of forcing data, in the same order and geo position as the cells. Tip: If time_axis is equal to the forcing time-axis, it is twice as fast.

Parameters:

• mid (str) – model identifier

• ta (TimeAxis) – specifies the time-axisfor the region-model, and thus the cells

• r_env (ARegionEnvironment) – A region environment with ready to use forcing data for all the cells.

Returns:

success. true if successfull, raises exception otherwise

Return type:

bool

set_current_state_as_initial_state((DrmClient)self, (object)mid) → bool :

set current state as initial state for the region model. the method .revert_to_initial_state will restore this state.

Parameters:

mid (str) – model identifier

Returns:

. true if succeeded

Return type:

bool

set_description((DrmClient)self, (object)mid, (object)description) → bool :

Set the user specified description string, typically a json formatted string.

Parameters:

mid (str) – model identifier

Returns:

. True if successful

Return type:

bool

set_region_parameter((DrmClient)self, (object)mid, (object)parameter) → bool :

set region parameter

Parameters:

• mid (str) – model identifier

• parameter (XXXXParameter) – strongly typed method stack parameter

Returns:

. true if succeeded

Return type:

bool

set_snow_sca_swe_collection((DrmClient)self, (object)mid, (object)catchment_id, (object)on_or_off) → bool :

enable/disable collection of snow sca|sca for calibration purposes

Parameters:

• mid (str) – model identifier

• catchment_id (int) – to enable snow calibration for, -1 means turn on/off for all

• on_or_off (bool) – on_or_off true|or false

Returns:

. true if succeeded

Return type:

bool

set_state((DrmClient)self, (object)mid, (object)state) → bool :

set the cell state

Parameters:

• mid (str) – model identifier

• state (StateWithIdVector) – strongly typed list of stack state with id vector

Returns:

. true if succeeded

Return type:

bool

set_state_collection((DrmClient)self, (object)mid, (object)catchment_id, (object)on_or_off) → bool :

enable state collection for specified or all cells

Parameters:

• mid (str) – model identifier

• catchment_id (int) – to enable state collection for, -1 means turn on/off for all

• on_or_off (bool) – on_or_off true|or false

Returns:

. true if succeeded

Return type:

bool

start_calibration((DrmClient)self, (object)mid, (object)p_start, (object)p_min, (object)p_max, (TargetSpecificationVector)spec, (CalibrationOption)opt) → bool :

Start calibration with specified parameters for the model given by ‘mid’

Parameters:

• () (opt) – model identifier

• () – starting parameters

• () – min-range for parameters

• () – max-range for parameters

• () – goal function specification, including reference series and weights

• () – optimizer options, like BOBYQA, GLOBAL,SCEUA or DREAM etc.

Returns:

. indicating success

Return type:

bool

property timeout_ms

Timout for remote server operations, in number milliseconds.

Type:

int

total_clients = 0

class shyft.hydrology.DrmServer

Bases: instance

The DRMS, distributed region model server provides the server part that implements the needed functionality to create, run and get results from hydrology region-models .Togehter with the DrmClient, it allow the Shyft hydrology region-model operations to be scaled out on several servers, giving providing support for system and analysis of any size

__init__((DrmServer)self) → None :

Creates a server object .

property alive_connections

returns currently alive connections to the server

Type:

int

property fx

server-side callable function(lambda) that takes two parameters: mid : the model id fx_arg: arbitrary string to pass to the server-side function The server-side fx is called when the client (or web-api) invoke the c.fx(mid,fx_arg). The signature of the callback function should be fx_cb(mid:str, fx_arg:str)->bool This feature is simply enabling the users to tailor server-side functionality in python! NOTE: Currently we do take exclusive lock on the model id, so that we avoid race conditions Examples:

>>> from shyft.hydrology import DrmServer
>>> s=DrmServer()
>>> def my_fx(mid:str, fx_arg:str)->bool:
>>>     print(f'invoked with mid={mid} fx_arg={fx_arg}')
>>>   # note we can use captured Server s here!>>>     return True
>>> # and then bind the function to the callback
>>> s.fx=my_fx
>>> s.start_server()
>>> : # later using client from anywhere to invoke the call
>>> fx_result=c.fx('my_model_id', 'my_args')

Type:

Callable[[str,str],bool]

get_listening_port((DrmServer)self) → int :

returns the port number it’s listening at for serving incoming request

get_max_connections((DrmServer)self) → int :

returns the maximum number of connections to be served concurrently

get_model()

object get_model(tuple args, dict kwds) :

returns the named model, so it can be inspected/modified WIP: needs to be sure that there is no activity on the model from the remote side

Returns:

Model: . Of the type as set by the client

get_model_ids((DrmServer)self) → StringVector :

returns a list of model ids (mids) that is alive and known in the server

Returns:

. Strongly typed list of strings naming the available models on the drms

Return type:

StringList

is_running((DrmServer)self) → bool :

true if server is listening and running

See also

start_server()

set_listening_ip((DrmServer)self, (object)ip) → None :

set the listening port for the service

Parameters:

ip (str) – ip or host-name to start listening on

Returns:

nothing.

Return type:

None

set_listening_port((DrmServer)self, (object)port_no) → None :

set the listening port for the service

Parameters:

• port_no (int) – a valid and available tcp-ip port number to listen on.

• 20000 (typically it could be) –

Returns:

nothing.

Return type:

None

set_max_connections((DrmServer)self, (object)max_connect) → None :

limits simultaneous connections to the server (it’s multithreaded, and uses on thread pr. connect)

Parameters:

max_connect (int) – maximum number of connections before denying more connections

See also

get_max_connections()

start_server((DrmServer)self) → int :

start server listening in background, and processing messages

See also

set_listening_port(port_no),is_running

Returns:

port_no. the port used for listening operations, either the value as by set_listening_port, or if it was unspecified, a new available port

Return type:

in

stop_server((DrmServer)self[, (object)ms=2000]) → None :

stop serving connections, gracefully.

See also

start_server()

class shyft.hydrology.RegionModelType

Bases: enum

Ref to DrmClient, used do specify what remote region-model type to create

PT_GS_K = shyft.hydrology._api.RegionModelType.PT_GS_K

PT_GS_K_OPT = shyft.hydrology._api.RegionModelType.PT_GS_K_OPT

PT_HPS_K = shyft.hydrology._api.RegionModelType.PT_HPS_K

PT_HPS_K_OPT = shyft.hydrology._api.RegionModelType.PT_HPS_K_OPT

PT_HS_K = shyft.hydrology._api.RegionModelType.PT_HS_K

PT_HS_K_OPT = shyft.hydrology._api.RegionModelType.PT_HS_K_OPT

PT_SS_K = shyft.hydrology._api.RegionModelType.PT_SS_K

PT_SS_K_OPT = shyft.hydrology._api.RegionModelType.PT_SS_K_OPT

PT_ST_HBV = shyft.hydrology._api.RegionModelType.PT_ST_HBV

PT_ST_K = shyft.hydrology._api.RegionModelType.PT_ST_K

PT_ST_K_HBV = shyft.hydrology._api.RegionModelType.PT_ST_K_HBV

PT_ST_K_OPT = shyft.hydrology._api.RegionModelType.PT_ST_K_OPT

R_PM_GS_K = shyft.hydrology._api.RegionModelType.R_PM_GS_K

R_PM_GS_K_OPT = shyft.hydrology._api.RegionModelType.R_PM_GS_K_OPT

R_PT_GS_K = shyft.hydrology._api.RegionModelType.R_PT_GS_K

R_PT_GS_K_OPT = shyft.hydrology._api.RegionModelType.R_PT_GS_K_OPT

names = {'PT_GS_K': shyft.hydrology._api.RegionModelType.PT_GS_K, 'PT_GS_K_OPT': shyft.hydrology._api.RegionModelType.PT_GS_K_OPT, 'PT_HPS_K': shyft.hydrology._api.RegionModelType.PT_HPS_K, 'PT_HPS_K_OPT': shyft.hydrology._api.RegionModelType.PT_HPS_K_OPT, 'PT_HS_K': shyft.hydrology._api.RegionModelType.PT_HS_K, 'PT_HS_K_OPT': shyft.hydrology._api.RegionModelType.PT_HS_K_OPT, 'PT_SS_K': shyft.hydrology._api.RegionModelType.PT_SS_K, 'PT_SS_K_OPT': shyft.hydrology._api.RegionModelType.PT_SS_K_OPT, 'PT_ST_HBV': shyft.hydrology._api.RegionModelType.PT_ST_HBV, 'PT_ST_K': shyft.hydrology._api.RegionModelType.PT_ST_K, 'PT_ST_K_HBV': shyft.hydrology._api.RegionModelType.PT_ST_K_HBV, 'PT_ST_K_OPT': shyft.hydrology._api.RegionModelType.PT_ST_K_OPT, 'R_PM_GS_K': shyft.hydrology._api.RegionModelType.R_PM_GS_K, 'R_PM_GS_K_OPT': shyft.hydrology._api.RegionModelType.R_PM_GS_K_OPT, 'R_PT_GS_K': shyft.hydrology._api.RegionModelType.R_PT_GS_K, 'R_PT_GS_K_OPT': shyft.hydrology._api.RegionModelType.R_PT_GS_K_OPT}

values = {0: shyft.hydrology._api.RegionModelType.PT_GS_K, 1: shyft.hydrology._api.RegionModelType.PT_GS_K_OPT, 2: shyft.hydrology._api.RegionModelType.PT_SS_K, 3: shyft.hydrology._api.RegionModelType.PT_SS_K_OPT, 4: shyft.hydrology._api.RegionModelType.PT_HS_K, 5: shyft.hydrology._api.RegionModelType.PT_HS_K_OPT, 6: shyft.hydrology._api.RegionModelType.PT_HPS_K, 7: shyft.hydrology._api.RegionModelType.PT_HPS_K_OPT, 8: shyft.hydrology._api.RegionModelType.R_PM_GS_K, 9: shyft.hydrology._api.RegionModelType.R_PM_GS_K_OPT, 10: shyft.hydrology._api.RegionModelType.PT_ST_K, 11: shyft.hydrology._api.RegionModelType.PT_ST_K_OPT, 12: shyft.hydrology._api.RegionModelType.PT_ST_HBV, 13: shyft.hydrology._api.RegionModelType.PT_ST_K_HBV, 14: shyft.hydrology._api.RegionModelType.R_PT_GS_K, 15: shyft.hydrology._api.RegionModelType.R_PT_GS_K_OPT}

class shyft.hydrology.SnowTilesState

Bases: instance

__init__((SnowTilesState)arg1) → None

__init__( (SnowTilesState)arg1, (DoubleVector)fw, (DoubleVector)lw) -> None

property fw

frozen water in the snowpack, unit (mm)

Type:

DoubleVector

property lw

liquid water in the snowpack, unit (mm)

Type:

DoubleVector

class shyft.hydrology.SnowTilesCalculator

Bases: instance

Tile based snow model method

This algorithm uses …

__init__((SnowTilesCalculator)arg1, (SnowTilesParameter)parameter) → None :

creates a calculator with given parameter

step((SnowTilesCalculator)self, (SnowTilesState)state, (SnowTilesResponse)response, (time)t0, (time)t1, (object)precipitation, (object)temperature) → None :

steps the model forward from t0 to t1, updating state and response

class shyft.hydrology.SnowTilesResponse

Bases: instance

__init__((SnowTilesResponse)arg1) → None

property outflow

average outflow, rain and snowmelt, for the cell, unit (mm/hour)

property sca

average sca as a fraction of total cell area, unit (-)

Type:

float

property swe

average swe for the cell, unit (mm)

Type:

float

shyft.hydrology.percentiles(tsv: TsVector, time_axis: TimeAxis, percentile_list: IntVector) → TsVector