API documentation ¶

get_timeseries_attribute(target: Union[UUID, str, AttributeBase], full_attribute_info: bool = False) → TimeseriesAttribute[source]¶

Request information associated with a Mesh time series attribute from the Mesh model.

Parameters

target – Mesh time series attribute to be read. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attribute will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.
ValueError – Raised if given attribute ID or path points to an attribute of different type than TimeseriesAttribute.

get_timeseries_resource_info(timeseries_key: int) → TimeseriesResource[source]¶

Request information (like curve type or resolution) associated with a physical or virtual time series.

Parameters: timeseries_key – integer that only applies to a specific physical or virtual time series.
Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

get_xy_sets(target: Union[UUID, str, AttributeBase], start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, versions_only: bool = False) → List[XySet][source]¶

Get zero or more XY-sets from an XY-set attribute on the server.

An XY-set attribute is either versioned, with a kind XYZSeriesAttribute, or unversioned, with a kind XYSetAttribute.

Parameters

target – the GUID or the path of an XY-set attribute.
start_time – the (inclusive) start of the interval to retrieve XY sets in for versioned XY-set attributes. Must be None for unversioned attributes.
end_time – the (exclusive) end of the interval to retrieve XY sets in for versioned XY-set attributes. Must be None for unversioned attributes.
versions_only – don’t retrieve XY-set curves, only valid_from_time.

Returns

A list of XySet. The list always contains one element for unversioned attributes, and zero or more elements for versioned attributes.

For versioned attributes the method will return all XY sets that are valid in [start_time, end_time). This may include the last XY set that started its validity period before the interval.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed
TypeError – on invalid arguments (see above).

See also

history_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → HistoryFunctions[source]¶

Access to History functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all history functions.

list_models() → List[Object][source]¶

List all Mesh models. Model is a root object that does not have an owner.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

open() → None[source]¶

Request to open a session on the Mesh server. An opened session must be closed using the same Session object.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed

read_timeseries_points(target: Union[UUID, str, int, AttributeBase], start_time: datetime, end_time: datetime) → Timeseries[source]¶

Reads time series points for the specified time series in the given interval.

If there are too many points in the response you might get a StatusCode.RESOURCE_EXHAUSTED error. See: gRPC communication.

For information about datetime arguments and time zones refer to Date times and time zones.

Parameters

target – Mesh attribute, virtual or physical time series. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed
RuntimeError – Error message raised if the input is not valid
TypeError – Error message raised if the returned result from the request is not as expected

rollback() → None[source]¶

Discard changes in the Mesh session.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed

run_inflow_calculation(model: str, area: str, water_course: str, start_time: datetime, end_time: datetime, *, resolution: timedelta = None, return_datasets: bool = False) → Iterator[None][source]¶

Run an inflow calculation using HydSim on the Mesh server.

In case of running an inflow calculation on longer interval and with return_datasets enabled you might get a StatusCode.RESOURCE_EXHAUSTED error. See: gRPC communication.

Parameters

model – The name of the Mesh model in which the inflow calculation exists.
area – The area of the water course to calculate.
water_course – The water course to calculate.
start_time – The (inclusive) start of the calculation interval.
end_time – The (exclusive) end of the calculation interval.
resolution – The resolution of the simulation. The default resolution of the inflow calculation case is used if this is left as None. Officially supported resolutions are 5, 10, 15, and 60 minutes.
return_datasets – Generate and return HydSim datasets that can be used by Volue to diagnose issues with inflow calculations. For performance reasons this should be false when not trying to diagnose an issue.

Returns

An iterator of None. In future versions this iterator will yield log messages, datasets, and potentially more. The calculation is done when the iterator is exhausted.

Exhausting the iterator without an exception does not guarantee that the calculation completed successfully. To determine that you must analyze the calculation’s result time series and the log messages from the server.

Raises

TypeError –
grpc.RpcError –

run_simulation(model: str, case: str, start_time: datetime, end_time: datetime, *, resolution: timedelta = None, scenario: int = None, return_datasets: bool = False) → Iterator[None][source]¶

Run a hydro simulation using HydSim on the Mesh server.

In case of running a simulation on longer interval and with return_datasets enabled you might get a StatusCode.RESOURCE_EXHAUSTED error. See: gRPC communication.

This function is experimental and subject to larger changes.

Parameters

model – The name of the Mesh model in which the simulation case exists.
case – The names of the case group and simulation case in the form ‘CaseGroup/CaseName’.
start_time – The (inclusive) start of the simulation interval.
end_time – The (exclusive) end of the simulation interval.
resolution – The resolution of the simulation. The default resolution of the simulation case is used if this is left as None. Officially supported resolutions are 5, 10, 15, and 60 minutes.
scenario – The scenario(s) to run. All scenarios are run if left as None, no scenarios are run if set as -1, and a specific numbered scenario is run if set as the number of that scenario.
return_datasets – Generate and return HydSim datasets that can be used by Volue to diagnose issues with hydro simulations. For performance reasons this should be false when not trying to diagnose an issue.

Returns

An iterator of None. In future versions this iterator will yield log messages, datasets, and potentially more. The simulation is done when the iterator is exhausted.

Exhausting the iterator without an exception does not guarantee that the simulation completed successfully. To determine that you must analyze the simulation’s result time series and the log messages from the server.

Raises

TypeError –
grpc.RpcError –

search_for_attributes(target: Union[UUID, str, Object], query: str, full_attribute_info: bool = False) → List[AttributeBase][source]¶

Use the Mesh search language to find Mesh attributes in the Mesh model.

Parameters

target – Start searching at the target object. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
query – A search formulated using the Mesh search language.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object(s) will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

search_for_objects(target: Union[UUID, str, Object], query: str, full_attribute_info: bool = False, attributes_filter: Optional[AttributesFilter] = None) → List[Object][source]¶

Use the Mesh search language to find Mesh objects in the Mesh model.

Parameters

target – Start searching at the target object. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
query – A search formulated using the Mesh search language.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object(s) will be returned, otherwise only name, path, ID and value(s).
attributes_filter – Filtering criteria for what attributes owned by object(s) should be returned. By default all attributes are returned.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

search_for_timeseries_attributes(target: Union[UUID, str, Object], query: str, full_attribute_info: bool = False) → List[TimeseriesAttribute][source]¶

Use the Mesh search language to find Mesh time series attributes in the Mesh model.

Parameters

target – Start searching at the target object. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
query – A search formulated using the Mesh search language.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object(s) will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

statistical_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → StatisticalFunctions[source]¶

Access to Statistical functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all statistical functions.

transform_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → TransformFunctions[source]¶

Access to Transform functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all transformation functions.

update_link_relation_attribute(target: Union[UUID, str, AttributeBase], new_target_object_ids: List[UUID], append: bool = False) → None[source]¶

Update an existing Mesh link relation (non-versioned) attribute in the Mesh model.

Parameters

target – Mesh one-to-one or one-to-many link relation (non-versioned) attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
new_target_object_ids – List of objects the link relation will point to. For one-to-one link relation this must contain zero or one new_target_object_ids. If there is no new_target_object_ids provided then currently existing target object will be removed. If updating a one-to-many link relation attribute this may contain zero, one or more new_target_object_ids`s. If there is no `new_target_object_ids provided and append is set to False then all currently existing target objects will be removed.
append – If set to True for a one-to-many link relation attribute this will append target_object_ids to already existing ones. If set to False then all currently existing target objects will be replaced by target_object_ids. For one-to-one link relation attribute this must set to False.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

update_object(target: Union[UUID, str, Object], new_name: Optional[str] = None, new_owner_attribute: Optional[Union[UUID, str, AttributeBase]] = None) → None[source]¶

Update an existing Mesh object in the Mesh model. New owner of the object must be a one-to-one or one-to-many ownership relation attribute. E.g.: for SomePowerPlant1 object with path: - Model/SimpleThermalTestModel/ThermalComponent.ThermalPowerToPlantRef/SomePowerPlant1

Parameters

target – Mesh object to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths
new_name – New name for the object.
new_owner_attribute – New owner of the object. It must be a one-to-one (object value type = “ElementAttributeDefinition”) or one-to-many (object value type = “ElementCollectionAttributeDefinition”) ownership relation attribute. It could be a Universal Unique Identifier or a path in the Mesh model.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

update_rating_curve_versions(target: Union[UUID, str, AttributeBase], start_time: datetime, end_time: datetime, new_versions: List[RatingCurveVersion]) → None[source]¶

Replace rating curve versions on an rating curve attribute on the server.

The update operation deletes all versions in the [start_time, end_time) interval, and inserts the new versions.

Parameters

target – the ID or the path of an rating curve attribute.
start_time – the (inclusive) start of the edit interval.
end_time – the (exclusive) end of the edit interval.
new_versions – the list of rating curve versions to insert. All versions must be within [start_time, end_time) interval and sorted by valid_from_time.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

update_simple_attribute(target: Union[UUID, str, AttributeBase], value: Union[int, float, bool, str, datetime, List[int], List[float], List[bool], List[str], List[datetime]]) → None[source]¶

Update an existing Mesh simple attribute’s value in the Mesh model. Simple attribute is a singular type or collection of the following types: - double (float in Python) - integer (int in Python) - boolean (bool in Python) - string (str in Python) - UTC time (datetime in Python)

Parameters

target – Mesh attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
value – New simple attribute value. It can be one of following simple types: bool, float, int, str, datetime or a list of simple types.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

update_timeseries_attribute(target: Union[UUID, str, AttributeBase], new_local_expression: Optional[str] = None, new_timeseries_resource_key: Optional[int] = None) → None[source]¶

Update meta data of an existing Mesh time series attribute’s in the Mesh model.

Parameters

target – Mesh time series attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
new_local_expression – New local expression.
new_timeseries_resource_key – Time series key of a new time series resource (physical or virtual) to connect to the time series attribute. To disconnect time series attribute from already connected time series resource set this argument to 0.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

update_timeseries_resource_info(timeseries_key: int, new_curve_type: Optional[Curve] = None, new_unit_of_measurement: Optional[str] = None) → None[source]¶

Update information associated with a physical or virtual time series.

Parameters

timeseries_key – integer that only applies to a specific physical or virtual time series.
new_curve_type – set new curve type.
new_unit_of_measurement – set new unit of measurement.

Note

Specify which ever of the new_* fields you want to update.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

update_versioned_one_to_many_link_relation_attribute(target: Union[UUID, str, AttributeBase], new_entries: List[List[LinkRelationVersion]]) → None[source]¶

Update an existing Mesh versioned one-to-many link relation attribute in the Mesh model.

Parameters

target – Mesh one-to-many versioned link relation attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
new_entries – the list of lists of link relation versions to insert. The first level list represents entries. Each entry can have multiple link relation versions.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

update_versioned_one_to_one_link_relation_attribute(target: Union[UUID, str, AttributeBase], start_time: datetime, end_time: datetime, new_versions: List[LinkRelationVersion]) → None[source]¶

Update an existing Mesh versioned one-to-one link relation attribute in the Mesh model.

Parameters

target – Mesh one-to-one versioned link relation attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
start_time – the (inclusive) start of the edit interval.
end_time – the (exclusive) end of the edit interval.
new_versions – the list of link relation versions to insert. All versions must be within [start_time, end_time) interval.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

update_xy_sets(target: Union[UUID, str, AttributeBase], start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, new_xy_sets: List[XySet] = []) → None[source]¶

Replace XY sets on an XY-set attribute on the server.

An XY-set attribute is either versioned, with a kind XYZSeriesAttribute, or unversioned, with a kind XYSetAttribute.

When applied to an unversioned attribute the update_xy_sets operation removes the existing XY-set, and replaces it with the contents of xy_sets, which must contain zero or one XY-set.

When applied to a versioned attribute the operation deletes all versions in the interval [start_time, end_time), and inserts the new versions in xy_sets.

Parameters

target – the GUID or the path of an XY-set attribute.
start_time – the (inclusive) start of the edit interval. Must be None for unversioned XY-set attributes.
end_time – the (exclusive) end of the edit interval. Must be None for unversioned XY-set attributes.
new_xy_sets – the list of XY-sets to insert. Must contain zero or one element for unversioned attributes. All elements must be within [start_time, end_time) for versioned attributes.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed
TypeError – on invalid arguments (see above).

See also

write_timeseries_points(timeseries: Timeseries) → None[source]¶

Writes time series points for the specified time series in the given interval. Resolution of the time series does not need to be set when writing time series.

If there are too many points in the request you will the Mesh server will discard it and return StatusCode.RESOURCE_EXHAUSTED. See: gRPC communication.

Parameters: timeseries – The modified time series.
Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

connect_to_session(session_id: Optional[UUID]) → Session[source]¶

Create a session with a given session id, the id of the session you are (or want to be) connected to.

Parameters: session_id – The id of the session you are (or want to be) connected to.

Note

This is handled locally. No communication with the server is involved. Any subsequent use of the session object will communicate with the Mesh server. If the given session_id is a valid open session on the Mesh server, the session is now open and can be used. If the session_id is not a valid open session an exception will be raised when trying to use the session.

create_session() → Session[source]¶: Create a new session.

Note

This is handled locally. No communication with the server is involved. You will need to open the session before it will be created on the Mesh server.

get_user_identity() → UserIdentity[source]¶

Request information about the user authorized to work with the Mesh server.

Note

Does not require an open session.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

get_version() → VersionInfo[source]¶

Request version information of the connected Mesh server.

Note

Does not require an open session.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

classmethod insecure(target: str, *, grpc_max_receive_message_length: Optional[int] = None) → C[source]¶

Creates an insecure connection to a Mesh server.

Parameters

target – The server address.
grpc_max_receive_message_length – Maximum inbound gRPC message size in bytes. By default the maximum inbound gRPC message size is 4MB.

revoke_access_token() → None[source]¶

Revokes Mesh token if user no longer should be authenticated.

Note

Does not require an open session.

Raises

RuntimeError – Error message raised if the connection is not using Kerberos authentication.
grpc.RpcError – Error message raised if the gRPC request could not be completed.

update_external_access_token(access_token: str) → None[source]¶

Updates external access token used for connection to Mesh.

Parameters: access_token – New access token to be added to authorization header to each server request.

Note

Does not require an open session.

Raises: RuntimeError – Error message raised if the connection is not using external access token.

classmethod with_external_access_token(target: str, root_certificates: Optional[str], access_token: str, *, grpc_max_receive_message_length: Optional[int] = None) → C[source]¶

Creates an encrypted connection to a Mesh server and will add provided access token to authorization header to each server request.

This is used for setups with external identity providers that generate access tokens to the Mesh server.

Parameters

target – The server address.
root_certificates – The PEM-encoded TLS root certificates as a byte string, or None to retrieve them from a default location chosen by the gRPC runtime.
access_token – Token obtained externally, used to get access to Mesh server.
grpc_max_receive_message_length – Maximum inbound gRPC message size in bytes. By default the maximum inbound gRPC message size is 4MB.

classmethod with_kerberos(target: str, root_certificates: Optional[str], service_principal: str, user_principal: Optional[str] = None, *, grpc_max_receive_message_length: Optional[int] = None) → C[source]¶

Creates an encrypted and authenticated connection to a Mesh server.

This call will perform a Kerberos authentication flow towards Active Directory and the Mesh server using the supplied principal names. If successful the returned connection will then use that authenticated identity for all calls to the Mesh service.

The authentication is time-limited. When close to expiration the library will perform another authentication flow as part of the next gRPC call. This will lead to increased latency on calls where a re-authentication is necessary, but should otherwise be invisible to the user.

Parameters

target – The server address.
root_certificates – The PEM-encoded TLS root certificates as a byte string, or None to retrieve them from a default location chosen by the gRPC runtime.
service_principal – The Kerberos service principal name for the Mesh service. For example ‘HOSTserver.at.host’.
user_principal – The Kerberos user principal name. For example ‘aduser`.
grpc_max_receive_message_length – Maximum inbound gRPC message size in bytes. By default the maximum inbound gRPC message size is 4MB.

classmethod with_tls(target: str, root_certificates: Optional[str], *, grpc_max_receive_message_length: Optional[int] = None) → C[source]¶

Creates an encrypted connection to a Mesh server.

Parameters

target – The server address.
root_certificates – The PEM-encoded TLS root certificates as a byte string, or None to retrieve them from a default location chosen by the gRPC runtime.
grpc_max_receive_message_length – Maximum inbound gRPC message size in bytes. By default the maximum inbound gRPC message size is 4MB.

class volue.mesh.AttributeBase(proto_attribute: Attribute, init_definition: bool = False)[source]¶

Base class for Mesh Attribute.

Represents common information for all kinds of attributes. Mesh Attribute is an instance of Attribute Definition in the Mesh Model and has always an owner of Object type. It has some type (e.g. DoubleAttribute or BoolCollectionAttribute).

Refer to documentation for more details: Mesh attribute.

class AttributeBaseDefinition(proto_definition: AttributeDefinition)[source]¶: Attribute definition common for all kinds of attributes.

class volue.mesh.AttributesFilter(name_mask: Optional[List[str]] = None, tag_mask: Optional[List[str]] = None, namespace_mask: Optional[List[str]] = None, return_no_attributes: bool = False)[source]¶

Defines what attributes need to be returned in response message.

Name mask: Attribute name uniquely identifies attribute within given object. If set then only attributes set in the name mask are read. If any other mask: tag or namespace or return_no_attributes flag is also set then an error will be returned. The attribute name provided in the mask must be equal to the actual attribute name in the model. Note: Regular expressions are not supported. See examples below for more details.

Tag mask: Each attribute can have zero, one or more tags. If the tag mask is set then only attributes with at least one tag set in the field mask are read. If multiple tags are provided then all attributes having at least one of them are returned (logical OR). If name mask or return_no_attributes flag is also set then an error will be returned. It is allowed to have both: tag mask and namespace mask set. Note: Regular expressions are not supported. See examples below for more details.

Namespace mask: Each attribute can have zero, one or more namespaces. If the namespace mask is set then only attributes with at least one namespace set in the field mask are read. If multiple namespaces are provided in the mask then all attributes having at least one of them are returned (logical OR). Namespace mask does not accept entries with namespaces concatenated with dots ‘.’. Each namespace mask entry must be a separate namespace. If name mask or return_no_attributes flag is also set then an error will be returned. It is allowed to have both: tag mask and namespace mask set. Note: Regular expressions are not supported. See examples below for more details.

`return_no_attributes` flag: If set to True then no attributes will be returned. If any mask: name, tag or namespace is also set then an error will be returned. Default value is False.

Multiple attributes may have the same tag or namespace. If both: tag_mask and namespace_mask are provided then only attributes that meet both criteria are returned (intersection/logical AND).

Note: If no masks are provided then all attributes will be returned.

Example 1:

Arg: names is set to “Price,Volume,Production” Response: All attributes with names “Price”, “Volume” or “Production” will be returned. Note: tag_mask or namespace_mask will be ignored even if set.

Example 2:

Arg: tag_mask is set to “ProductionAttributes,LocationAttributes” Response: All attributes with tag name “ProductionAttributes” or “LocationAttributes” will be returned. Note: If attributes A1, A2 have tag “ProductionAttributes” and A3 has “LocationAttributes” then all three attributes (A1, A2 and A3) will be returned. Exactly the same rules apply to namespace_mask.

Example 3:

Arg: namespace_mask is set to “Hydro,Wind”. Response: All attributes with namespace “Hydro” or “Wind” will be returned. Note: Suppose there are the following attributes: - A1 (namespace “EnergySystem.Hydro”) - A2 (namespace “EnergySystem.Wind”) - A3 (namespace “EnergySystem.Carbon”) - A4 (namespace “EnergySystem.Hydro.Small”) - A5 (namespace “Hydro.Normal”)

In this case attributes A1, A2, A4 and A5 will be returned.

Example 4:

Arg: tag_mask is set to “ProductionAttributes”, namespace_mask is set to “Hydro,Wind”. Response: All attributes with tag name “ProductionAttributes” and namespace “Hydro” or “Wind” will be returned. Note: Suppose there are the following attributes: - A1 (tag “ProductionAttributes”, namespace “Hydro”) - A2 (tag “ProductionAttributes”, namespace “Wind”) - A3 (tag “ProductionAttributes”, namespace “Carbon”) - A4 (tag “LocationAttributes”, namespace “Hydro”) - A5 (tag “LocationAttributes”, namespace “Wind”)

In this case attributes A1 and A2 will be returned.

name_mask: Optional[List[str]] = None¶

namespace_mask: Optional[List[str]] = None¶

return_no_attributes: bool = False¶

tag_mask: Optional[List[str]] = None¶

class volue.mesh.Authentication(parameters: Parameters, target: str, channel_credentials: ChannelCredentials)[source]¶

Authentication services for authentication and authorization to Mesh server using kerberos.

The flow is as follows:

Obtain token from Kerberos to access specified service (SPN) with Mesh server running on it.
Send this token to Mesh gRPC server (using AuthenticateKerberos).
In return Mesh may respond with:
1. Server challenge to be verified and processed by client (using Kerberos). In this case the authentication is not yet completed and client should respond to the server with next Kerberos generated token.
2. Mesh token - to be used in subsequent calls to Mesh that require authentication.

Note

Token duration - tokens are valid for 1 hour. After this time a new token needs to be acquired.

class KerberosTokenIterator(service_principal: str, user_principal: str)[source]¶

Kerberos token iterator to be used with AuthenticateKerberos streaming gRPC. Sends tokens to be processed by the Mesh server and processes tokens received from the server.

__init__(service_principal: str, user_principal: str)[source]¶

Parameters

service_principal – Name of an active directory service, e.g.: ‘HOST/hostname.ad.examplecompany.com.
user_principal – Name of an active directory user, e.g.: ‘aduser.name’.

process_response(server_kerberos_token: bytes) → None[source]¶

Sets new response from Mesh with kerberos token to be processed by client.

Parameters: server_kerberos_token – The kerberos token.

signal_final_response_received() → None[source]¶: Signals to the iterator that final response from server was received. Cancel any preparation (meaning exit wait) as there is no need to prepare next request.

class Parameters(service_principal: str, user_principal: Optional[str] = None)[source]¶

Authentication parameters.

Parameters

service_principal – Name of an active directory service, e.g.: ‘HOST/hostname.ad.examplecompany.com.
user_principal – Name of an active directory user, e.g.: ‘aduser.name’.

service_principal: str¶

user_principal: Optional[str] = None¶

__init__(parameters: Parameters, target: str, channel_credentials: ChannelCredentials)[source]¶

If Mesh gRPC server is running as a service user, for example LocalSystem, NetworkService or a user account with a registered service principal name then it is enough to provide hostname as service principal, e.g.: ‘HOST/hostname.ad.examplecompany.com’

If Mesh gRPC server is running as a user account without registered service principal name then it is enough to provide user account name running Mesh server as service principal, e.g.: ad\user.name’ or r’aduser.name’.

Note

winkerberos converts service principal name if provided in RFC-2078 format. ‘@’ is converted to ‘/’ if there is no ‘/’ character in the service principal name.

E.g.: service@hostname Would be converted to: service/hostname

Parameters

parameters – Authentication parameters.
target – Mesh server host name in the form an IP or domain name.
channel_credentials – An encapsulation of the data required to create a secure Channel.

delete_access_token()[source]¶: Deletes (resets) current Mesh token if no longer needed. auth_service.RevokeAccessToken call is made in Connection classes.

get_token() → None[source]¶

Gets Mesh token used for authorization in other calls to Mesh server.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.
(win)kerberos.GSSError – Errors from kerberos.
RuntimeError – Invalid token duration.

is_token_valid() → bool[source]¶

Checks if current token is still valid.

Returns: Flag if token is valid.

class volue.mesh.HydSimDataset(name: str, data: bytes)[source]¶

A representation of data used in a hydro simulation or inflow calculation.

The HydSim team may use a dataset to diagnose issues. When Volue requests a dataset we recommend storing datasets with filename name and contents from data and then sending those files to Volue.

data: bytes¶

name: str¶

class volue.mesh.LinkRelationAttribute(proto_attribute: Attribute)[source]¶

Represents a link relation Mesh Attribute.

Link relation attributes connect two objects, but object pointing to another object does not own it like in OwnershipRelationAttribute.

There are two types of link relation attributes (value_type is provided in the parenthesis): - one-to-one (ReferenceAttributeDefinition) - one-to-many (ReferenceCollectionAttributeDefinition)

There is also a versioned link relation, where the target object can change over time. See VersionedLinkRelationAttribute.

Refer to documentation for more details: Mesh attribute and Relations.

class LinkRelationAttributeDefinition(proto_definition: AttributeDefinition)[source]¶: Attribute definition for link relation attribute.

class volue.mesh.LinkRelationVersion(target_object_id: Optional[UUID], valid_from_time: datetime)[source]¶

Represents a link relation version.

Contains target object ID and timestamp with the time at which the version becomes active. If target object ID is None, then it means the target object is “empty”.

See also

target_object_id: Optional[UUID]¶

valid_from_time: datetime¶

class volue.mesh.LogMessage(level: int, message: str)[source]¶

Represents a log message from the Mesh server.

These are returned as a response from hydro simulations and inflow calculations.

level: int¶

message: str¶

class volue.mesh.Object(id: ~uuid.UUID, path: str, name: str, type_name: str, owner_id: ~typing.Optional[~uuid.UUID], owner_path: ~typing.Optional[str], attributes: ~typing.Dict[str, ~volue.mesh._attribute.AttributeBase] = <factory>)[source]¶

Represents a Mesh Object.

Mesh Object is an instance of Object Definition in the Mesh Model. Refer to documentation for more details: Mesh object.

attributes: Dict[str, AttributeBase]¶

id: UUID¶

name: str¶

owner_id: Optional[UUID]¶

owner_path: Optional[str]¶

path: str¶

type_name: str¶

class volue.mesh.OwnershipRelationAttribute(proto_attribute: Attribute)[source]¶

Represents an ownership relation Mesh Attribute.

Ownership relation attributes connect two objects. The owned object’s owner is always an ownership relation attribute that belongs to some other object.

There are two types of ownership relation attributes (value_type is provided in the parenthesis): - one-to-one (ElementAttributeDefinition) - one-to-many (ElementCollectionAttributeDefinition)

When creating a new object the owner must be an ownership relation attribute of one-to-many type (ElementCollectionAttributeDefinition).

Refer to documentation for more details: Mesh attribute and Relations.

class OwnershipRelationAttributeDefinition(proto_definition: AttributeDefinition)[source]¶: Attribute definition for ownership relation attribute.

class volue.mesh.RatingCurveSegment(x_range_until: float, factor_a: float, factor_b: float, factor_c: float)[source]¶

Represents a rating curve segment.

Contains a, b and c factors for the discharge formula. Additionally each segment i stores a 64 bit floating point x_range_until value and is valid for a range of x values [x_range_until[i-1], x_range_until[i]).

See also

factor_a: float¶

factor_b: float¶

factor_c: float¶

x_range_until: float¶

class volue.mesh.RatingCurveVersion(x_range_from: float, valid_from_time: datetime, x_value_segments: List[RatingCurveSegment])[source]¶

Represents a rating curve version.

Contains rating curve segments, timestamp with the time at which the version becomes active and a threshold indicating the minimal x value for the curve. For x < x_range_from for the given version the f(x) = nan.

See also

valid_from_time: datetime¶

x_range_from: float¶

x_value_segments: List[RatingCurveSegment]¶

class volue.mesh.SimpleAttribute(proto_attribute: Attribute)[source]¶

Represents simple Mesh Attributes.

A simple attribute means an attribute that is defined by a single value or a collection of single values.

The value can be of the following type (value_type is provided in the parenthesis): - integer (Int64AttributeDefinition) - collection of integers (Int64ArrayAttributeDefinition) - double (DoubleAttributeDefinition) - collection of doubles (DoubleArrayAttributeDefinition) - boolean (BooleanAttributeDefinition) - collection of booleans (BooleanArrayAttributeDefinition) - string (StringAttributeDefinition) or collection of strings (StringArrayAttributeDefinition) - datetime (UtcDateTimeAttributeDefinition) or collection of datetimes (UtcDateTimeArrayAttributeDefinition)

Types: integer (single or collection) and double (single or collection) may have additionally the following fields defined: - minimum_value - maximum_value - unit_of_measurement

Refer to documentation for more details: Mesh attribute.

class SimpleAttributeDefinition(proto_definition: AttributeDefinition)[source]¶: Attribute definition for simple attributes.

class volue.mesh.Timeseries(table: Table = None, resolution: Optional[Resolution] = None, start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, timskey: Optional[int] = None, uuid_id: Optional[UUID] = None, full_name: Optional[str] = None)[source]¶

Represents a Mesh time series.

Contains an arrow table with a schema of 3 fields (utc_time, flags, value.) Utc_time is the timestamps of the points (milliseconds since UNIX epoch 1970-01-01) Flags Value is the actual data for the given timestamp.

See also

Time series

class Curve(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

A curve type of a time series. It specifies how the values are laid out relative to each other.

Parameters

UNKNOWN –
STAIRCASESTARTOFSTEP –
PIECEWISELINEAR –
STAIRCASE –

PIECEWISELINEAR = 2¶

STAIRCASE = 3¶

STAIRCASESTARTOFSTEP = 1¶

UNKNOWN = 0¶

class PointFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Information about certain action that has been performed on the values and the state. It is 32 bit flag setting the status for the point. Enum values could be used in combination (logical “OR”), e.g.: flag = MISSING | SUSPECT

There are more options than the ones exposed here.

Default is OK = 0.

Parameters

OK – Default value, in most cases it should be used when writing new points with correct new values.
NOT_OK –
MISSING – Point value is missing, e.g: when reading physical time series in an interval where the time series has no values or reading calculation time series where all calculation components are missing values for the given interval.
SUSPECT – Point value is suspected, e.g. when reading a calculation time series in an interval where at least one component (like physical time series points) is missing values. If all calculation components are missing values then a MISSING flag is set.

MISSING = 67108864¶

NOT_OK = 1073741824¶

OK = 0¶

SUSPECT = 33554432¶

class Resolution(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

The resolution of values in the time series. It specifies the time interval between each value.

Parameters

UNSPECIFIED –
UNDEFINED –
BREAKPOINT –
MIN15 –
MIN30 –
HOUR –
DAY –
WEEK –
MONTH –
YEAR –

BREAKPOINT = 1¶

DAY = 4¶

HOUR = 3¶

MIN15 = 2¶

MIN30 = 8¶

MONTH = 6¶

UNDEFINED = 9¶

UNSPECIFIED = 0¶

WEEK = 5¶

YEAR = 7¶

__init__(table: Table = None, resolution: Optional[Resolution] = None, start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, timskey: Optional[int] = None, uuid_id: Optional[UUID] = None, full_name: Optional[str] = None)[source]¶

A representation of a time series. If start_time and end_time are not provided explicitly they will be taken from PyArrow table. Providing broader time interval (start_time and end_time) could be used when writing new time series points, then all existing time series points within the time interval that are not covered by new time series points will be removed. E.g. start_time is set to May 1st, end_time is set to May 3rd and PyArrow table has points defined only for May 2nd, then all old points on May 1st and 3rd will be removed and new points will be set for May 2nd.

For information about datetime arguments and time zones refer to Date times and time zones.

To only remove existing time series points without writing any new ones: - Provide empty PyArrow table with schema (table = Timeseries.schema.empty_table()) - Provide explicitly the interval for points removal by specifying start_time and end_time.

Parameters

table – The arrow table containing the timestamps, flags and values.
resolution – The resolution of the time series. Does not need to be set when writing time series.
start_time – The start date and time of the time series interval.
end_time – The end date and time of the time series interval.
timskey – Integer that only applies to a specific physical or virtual time series.
uuid_id – Universal Unique Identifier for Mesh objects.
full_name – Path in the Mesh model. See: objects and attributes paths.

Raises

TypeError – Error message raised if PyArrow table schema is invalid.

property is_calculation_expression_result: bool¶

Checks if a time series is a calculated or a physical or virtual time series.

Note

If time series does not have timskey, uuid and full_name set, then it is an ad-hoc calculation expression result (like e.g.: timeseries transformations). Refer to documentation ‘Concepts’ for more information.

Returns: True if it is a calculated time series

property number_of_points: int¶

Number of points inside the time series.

Returns: The number of points in the time series

schema = utc_time: timestamp[ms] flags: uint32 value: double¶

class volue.mesh.TimeseriesAttribute(proto_attribute: Attribute)[source]¶

Represents time series Mesh Attribute.

Time series attribute can be a:

reference to a physical time series: it has actual data (timestamps, values and flags) and meta data (e.g.: curve type, resolution, etc.).
reference to a virtual time series: it has defined an expression to calculate time series data (similar to calculation time series).
calculation time series: it has defined an expression to calculate time series data. The calculation expression can be defined on Attribute Definition level (template_expression) or overwritten for the given attribute (if it is then is_local_expression is set to True).

Note: physical and virtual time series are both called resource time series.

Refer to documentation for more details: Mesh attribute.

class TimeseriesAttributeDefinition(proto_definition: AttributeDefinition)[source]¶: Attribute definition for time series attribute.

class volue.mesh.TimeseriesResource(timeseries_key: int, path: str, name: str, temporary: bool, curve_type: Curve, resolution: Resolution, unit_of_measurement: Optional[str], virtual_timeseries_expression: Optional[str] = None)[source]¶

Represents a Mesh time series resource (either physical or virtual).

curve_type: Curve¶

name: str¶

path: str¶

resolution: Resolution¶

temporary: bool¶

timeseries_key: int¶

unit_of_measurement: Optional[str]¶

virtual_timeseries_expression: Optional[str] = None¶

class volue.mesh.UserIdentity(display_name: str, source: str, identifier: str)[source]¶

Represents a Mesh server user identity.

display_name - a human readable name identifying this user. This name should not be used as a unique identifier for the user as it may be identical between users and change over time.

source - security package name where the user identity came from. It is not a unique identifier of the security package instance.

identifier - uniquely identifies the user within given source instance, but not necessarily globally. Combining source and identifier does not guarantee to get globally unique identifier for the user as there may be different Active Directories using the same security packages (source) with duplicated user identifiers. However such situation is rather unlikely.

display_name: str¶

identifier: str¶

source: str¶

class volue.mesh.VersionInfo(version: str, name: str)[source]¶

Represents a Mesh server version information.

version - version number, e.g.: 2.5.2.32

name - friendly name of the Mesh server, e.g.: Volue Mesh Server.

name: str¶

version: str¶

class volue.mesh.VersionedLinkRelationAttribute(proto_attribute: Attribute)[source]¶

Represents a versioned link relation Mesh Attribute.

Versioned link relation, which is a link relation where the target object can change over time. It consists of a list of pairs: - Target object identifier. - Timestamp which indicates start of the period where the target object is active (linked to), the target object is active until the next target object in the list, if any, becomes active.

There are two types of versioned link relation attributes (value_type is provided in the parenthesis): - one-to-one (ReferenceSeriesAttributeDefinition) - one-to-many (ReferenceSeriesCollectionAttributeDefinition)

Refer to documentation for more details: Mesh attribute and Relations.

class VersionedLinkRelationEntry(versions: List[LinkRelationVersion])[source]¶

Represents a versioned link relation entry.

versions: List[LinkRelationVersion]¶

class volue.mesh.XyCurve(z: float, xy: List[Tuple[float, float]])[source]¶

A list of (x, y) pairs, indexed by a reference/z value.

See also

xy: List[Tuple[float, float]]¶

z: float¶

class volue.mesh.XySet(valid_from_time: Optional[datetime], xy_curves: List[XyCurve])[source]¶

A set of XY-curves.

If this set is part of a versioned XY-set attribute (XYZSeriesAttribute) the valid_from_time field contains a datetime with the start of the validity period for the XY-set. Otherwise it will be None.

See also

valid_from_time: Optional[datetime]¶

xy_curves: List[XyCurve]¶

volue.mesh.aio¶

Functionality that supports concurrency using asyncio.

class volue.mesh.aio.Connection(*args, **kwargs)[source]¶

class Session(calc_service: CalculationServiceStub, hydsim_service: HydsimServiceStub, model_service: ModelServiceStub, model_definition_service: ModelDefinitionServiceStub, session_service: SessionServiceStub, time_series_service: TimeseriesServiceStub, session_id: Optional[UUID] = None)[source]¶

This class supports the async with statement, because it’s an async contextmanager. https://docs.python.org/3/reference/datamodel.html#asynchronous-context-managers https://docs.python.org/3/reference/compound_stmts.html#async-with

async close() → None[source]¶

Request to close a session on the Mesh server.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed

Note

This method does not wait for the Mesh server to finish closing the session on the Mesh server.

async commit() → None[source]¶

Commit changes made in the Mesh session to the shared storage.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed

async create_object(target: Union[UUID, str, AttributeBase], name: str) → Object[source]¶

Create new Mesh object in the Mesh model. Owner of the new object must be a one-to-one or one-to-many ownership relation attribute. E.g.: for SomePowerPlant1 object with path: - Model/SimpleThermalTestModel/ThermalComponent.ThermalPowerToPlantRef/SomePowerPlant1

Owner will be the ThermalPowerToPlantRef attribute.

Parameters

target – Owner of the new object to be created. It must be a one-to-one (object value type = “ElementAttributeDefinition”) or one-to-many (object value type = “ElementCollectionAttributeDefinition”) ownership relation attribute. It could be a Universal Unique Identifier or a path in the Mesh model.
name – Name for the new object to create.

Returns

Created object with all attributes (no mask applied) and basic information: name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async create_physical_timeseries(path: str, name: str, curve_type: Curve, resolution: Resolution, unit_of_measurement: str) → TimeseriesResource[source]¶

async delete_object(target: Union[UUID, str, Object], recursive_delete: bool = False) → None[source]¶

Delete an existing Mesh object in the Mesh model.

Parameters

target – Mesh object to be deleted. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths
recursive_delete – If set then all child objects (owned by the object to be deleted) in the model will also be deleted.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

forecast_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → ForecastFunctionsAsync[source]¶

Access to Forecast functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all forecast functions.

async get_attribute(target: Union[UUID, str, AttributeBase], full_attribute_info: bool = False) → AttributeBase[source]¶

Request information associated with a Mesh attribute from the Mesh model.

Parameters

target – Mesh attribute to be read. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attribute will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async get_mc_file(model: str, case: str, start_time: datetime, end_time: datetime) → Union[Iterator[None], AsyncIterator[None]][source]¶

Generate Marginal Cost input using HydSim on the Mesh server.

Parameters

model – The name of the Mesh model in which the simulation case exists.
case – The names of the case group and simulation case in the form ‘CaseGroup/CaseName’.
start_time – The (inclusive) start of the simulation interval.
end_time – The (exclusive) end of the simulation interval.

Returns

An iterator of LogMessage`s followed by a single `str. The final string is the Marginal Cost input.

Raises

TypeError –
grpc.RpcError –

async get_object(target: Union[UUID, str, Object], full_attribute_info: bool = False, attributes_filter: Optional[AttributesFilter] = None) → Object[source]¶

Request information associated with a Mesh object from the Mesh model. Specify either object_id or object_path to a Mesh object.

Parameters

target – Mesh object to be read. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object will be returned, otherwise only name, path, ID and value(s).
attributes_filter – Filtering criteria for what attributes owned by object should be returned. By default all attributes are returned.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async get_rating_curve_versions(target: Union[UUID, str, AttributeBase], start_time: datetime, end_time: datetime, versions_only: bool = False) → List[RatingCurveVersion][source]¶

Get rating curve versions from an rating curve attribute on the server.

Parameters

target – the ID or the path of an rating curve attribute.
start_time – the (inclusive) start of the interval to retrieve rating curve versions.
end_time – the (exclusive) end of the interval to retrieve rating curve versions.
versions_only – retrieve only valid_from_time timestamps for each version, no other data like segments will be retrieved.

Returns

A list of RatingCurveVersion.

The method will return all rating curve versions that are valid in [start_time, end_time) interval. This may include the last rating curve version that started its validity period before the interval.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

async get_timeseries_attribute(target: Union[UUID, str, AttributeBase], full_attribute_info: bool = False) → TimeseriesAttribute[source]¶

Request information associated with a Mesh time series attribute from the Mesh model.

Parameters

target – Mesh time series attribute to be read. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attribute will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.
ValueError – Raised if given attribute ID or path points to an attribute of different type than TimeseriesAttribute.

async get_timeseries_resource_info(timeseries_key: int) → TimeseriesResource[source]¶

Request information (like curve type or resolution) associated with a physical or virtual time series.

Parameters: timeseries_key – integer that only applies to a specific physical or virtual time series.
Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

async get_xy_sets(target: Union[UUID, str, AttributeBase], start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, versions_only: bool = False) → List[XySet][source]¶

Get zero or more XY-sets from an XY-set attribute on the server.

An XY-set attribute is either versioned, with a kind XYZSeriesAttribute, or unversioned, with a kind XYSetAttribute.

Parameters

target – the GUID or the path of an XY-set attribute.
start_time – the (inclusive) start of the interval to retrieve XY sets in for versioned XY-set attributes. Must be None for unversioned attributes.
end_time – the (exclusive) end of the interval to retrieve XY sets in for versioned XY-set attributes. Must be None for unversioned attributes.
versions_only – don’t retrieve XY-set curves, only valid_from_time.

Returns

A list of XySet. The list always contains one element for unversioned attributes, and zero or more elements for versioned attributes.

For versioned attributes the method will return all XY sets that are valid in [start_time, end_time). This may include the last XY set that started its validity period before the interval.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed
TypeError – on invalid arguments (see above).

See also

history_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → HistoryFunctionsAsync[source]¶

Access to History functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all history functions.

async list_models() → List[Object][source]¶

List all Mesh models. Model is a root object that does not have an owner.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

async open() → None[source]¶

Request to open a session on the Mesh server. An opened session must be closed using the same Session object.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed

async read_timeseries_points(target: Union[UUID, str, int, AttributeBase], start_time: datetime, end_time: datetime) → Timeseries[source]¶

Reads time series points for the specified time series in the given interval.

If there are too many points in the response you might get a StatusCode.RESOURCE_EXHAUSTED error. See: gRPC communication.

For information about datetime arguments and time zones refer to Date times and time zones.

Parameters

target – Mesh attribute, virtual or physical time series. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed
RuntimeError – Error message raised if the input is not valid
TypeError – Error message raised if the returned result from the request is not as expected

async rollback() → None[source]¶

Discard changes in the Mesh session.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed

async run_inflow_calculation(model: str, area: str, water_course: str, start_time: datetime, end_time: datetime, *, resolution: timedelta = None, return_datasets: bool = False) → AsyncIterator[None][source]¶

Run an inflow calculation using HydSim on the Mesh server.

In case of running an inflow calculation on longer interval and with return_datasets enabled you might get a StatusCode.RESOURCE_EXHAUSTED error. See: gRPC communication.

Parameters

model – The name of the Mesh model in which the inflow calculation exists.
area – The area of the water course to calculate.
water_course – The water course to calculate.
start_time – The (inclusive) start of the calculation interval.
end_time – The (exclusive) end of the calculation interval.
resolution – The resolution of the simulation. The default resolution of the inflow calculation case is used if this is left as None. Officially supported resolutions are 5, 10, 15, and 60 minutes.
return_datasets – Generate and return HydSim datasets that can be used by Volue to diagnose issues with inflow calculations. For performance reasons this should be false when not trying to diagnose an issue.

Returns

An iterator of None. In future versions this iterator will yield log messages, datasets, and potentially more. The calculation is done when the iterator is exhausted.

Exhausting the iterator without an exception does not guarantee that the calculation completed successfully. To determine that you must analyze the calculation’s result time series and the log messages from the server.

Raises

TypeError –
grpc.RpcError –

async run_simulation(model: str, case: str, start_time: datetime, end_time: datetime, *, resolution: timedelta = None, scenario: int = None, return_datasets: bool = False) → AsyncIterator[None][source]¶

Run a hydro simulation using HydSim on the Mesh server.

In case of running a simulation on longer interval and with return_datasets enabled you might get a StatusCode.RESOURCE_EXHAUSTED error. See: gRPC communication.

This function is experimental and subject to larger changes.

Parameters

model – The name of the Mesh model in which the simulation case exists.
case – The names of the case group and simulation case in the form ‘CaseGroup/CaseName’.
start_time – The (inclusive) start of the simulation interval.
end_time – The (exclusive) end of the simulation interval.
resolution – The resolution of the simulation. The default resolution of the simulation case is used if this is left as None. Officially supported resolutions are 5, 10, 15, and 60 minutes.
scenario – The scenario(s) to run. All scenarios are run if left as None, no scenarios are run if set as -1, and a specific numbered scenario is run if set as the number of that scenario.
return_datasets – Generate and return HydSim datasets that can be used by Volue to diagnose issues with hydro simulations. For performance reasons this should be false when not trying to diagnose an issue.

Returns

An iterator of None. In future versions this iterator will yield log messages, datasets, and potentially more. The simulation is done when the iterator is exhausted.

Exhausting the iterator without an exception does not guarantee that the simulation completed successfully. To determine that you must analyze the simulation’s result time series and the log messages from the server.

Raises

TypeError –
grpc.RpcError –

async search_for_attributes(target: Union[UUID, str, Object], query: str, full_attribute_info: bool = False) → List[AttributeBase][source]¶

Use the Mesh search language to find Mesh attributes in the Mesh model.

Parameters

target – Start searching at the target object. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
query – A search formulated using the Mesh search language.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object(s) will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async search_for_objects(target: Union[UUID, str, Object], query: str, full_attribute_info: bool = False, attributes_filter: Optional[AttributesFilter] = None) → List[Object][source]¶

Use the Mesh search language to find Mesh objects in the Mesh model.

Parameters

target – Start searching at the target object. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
query – A search formulated using the Mesh search language.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object(s) will be returned, otherwise only name, path, ID and value(s).
attributes_filter – Filtering criteria for what attributes owned by object(s) should be returned. By default all attributes are returned.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async search_for_timeseries_attributes(target: Union[UUID, str, Object], query: str, full_attribute_info: bool = False) → List[TimeseriesAttribute][source]¶

Use the Mesh search language to find Mesh time series attributes in the Mesh model.

Parameters

target – Start searching at the target object. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
query – A search formulated using the Mesh search language.
full_attribute_info – If set then all information (e.g. description, value type, etc.) of attributes owned by the object(s) will be returned, otherwise only name, path, ID and value(s).

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

statistical_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → StatisticalFunctionsAsync[source]¶

Access to Statistical functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all statistical functions.

transform_functions(target: Union[UUID, str, int, AttributeBase, Object], start_time: datetime, end_time: datetime) → TransformFunctionsAsync[source]¶

Access to Transform functions.

Parameters

target – Mesh object, attribute, virtual or physical time series the calculation expression will be evaluated relative to. It could be a time series key, Universal Unique Identifier or a path in the Mesh model.
start_time – the start date and time of the time series interval
end_time – the end date and time of the time series interval

Returns

Object containing all transformation functions.

async update_link_relation_attribute(target: Union[UUID, str, AttributeBase], new_target_object_ids: List[UUID], append: bool = False) → None[source]¶

Update an existing Mesh link relation (non-versioned) attribute in the Mesh model.

Parameters

target – Mesh one-to-one or one-to-many link relation (non-versioned) attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
new_target_object_ids – List of objects the link relation will point to. For one-to-one link relation this must contain zero or one new_target_object_ids. If there is no new_target_object_ids provided then currently existing target object will be removed. If updating a one-to-many link relation attribute this may contain zero, one or more new_target_object_ids`s. If there is no `new_target_object_ids provided and append is set to False then all currently existing target objects will be removed.
append – If set to True for a one-to-many link relation attribute this will append target_object_ids to already existing ones. If set to False then all currently existing target objects will be replaced by target_object_ids. For one-to-one link relation attribute this must set to False.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

async update_object(target: Union[UUID, str, Object], new_name: Optional[str] = None, new_owner_attribute: Optional[Union[UUID, str, AttributeBase]] = None) → None[source]¶

Update an existing Mesh object in the Mesh model. New owner of the object must be a one-to-one or one-to-many ownership relation attribute. E.g.: for SomePowerPlant1 object with path: - Model/SimpleThermalTestModel/ThermalComponent.ThermalPowerToPlantRef/SomePowerPlant1

Parameters

target – Mesh object to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths
new_name – New name for the object.
new_owner_attribute – New owner of the object. It must be a one-to-one (object value type = “ElementAttributeDefinition”) or one-to-many (object value type = “ElementCollectionAttributeDefinition”) ownership relation attribute. It could be a Universal Unique Identifier or a path in the Mesh model.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async update_rating_curve_versions(target: Union[UUID, str, AttributeBase], start_time: datetime, end_time: datetime, new_versions: List[RatingCurveVersion]) → None[source]¶

Replace rating curve versions on an rating curve attribute on the server.

The update operation deletes all versions in the [start_time, end_time) interval, and inserts the new versions.

Parameters

target – the ID or the path of an rating curve attribute.
start_time – the (inclusive) start of the edit interval.
end_time – the (exclusive) end of the edit interval.
new_versions – the list of rating curve versions to insert. All versions must be within [start_time, end_time) interval and sorted by valid_from_time.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

async update_simple_attribute(target: Union[UUID, str, AttributeBase], value: Union[int, float, bool, str, datetime, List[int], List[float], List[bool], List[str], List[datetime]]) → None[source]¶

Update an existing Mesh simple attribute’s value in the Mesh model. Simple attribute is a singular type or collection of the following types: - double (float in Python) - integer (int in Python) - boolean (bool in Python) - string (str in Python) - UTC time (datetime in Python)

Parameters

target – Mesh attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
value – New simple attribute value. It can be one of following simple types: bool, float, int, str, datetime or a list of simple types.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async update_timeseries_attribute(target: Union[UUID, str, AttributeBase], new_local_expression: Optional[str] = None, new_timeseries_resource_key: Optional[int] = None) → None[source]¶

Update meta data of an existing Mesh time series attribute’s in the Mesh model.

Parameters

target – Mesh time series attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
new_local_expression – New local expression.
new_timeseries_resource_key – Time series key of a new time series resource (physical or virtual) to connect to the time series attribute. To disconnect time series attribute from already connected time series resource set this argument to 0.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

async update_timeseries_resource_info(timeseries_key: int, new_curve_type: Optional[Curve] = None, new_unit_of_measurement: Optional[str] = None) → None[source]¶

Update information associated with a physical or virtual time series.

Parameters

timeseries_key – integer that only applies to a specific physical or virtual time series.
new_curve_type – set new curve type.
new_unit_of_measurement – set new unit of measurement.

Note

Specify which ever of the new_* fields you want to update.

Raises: grpc.RpcError – Error message raised if the gRPC request could not be completed.

async update_versioned_one_to_many_link_relation_attribute(target: Union[UUID, str, AttributeBase], new_entries: List[List[LinkRelationVersion]]) → None[source]¶

Update an existing Mesh versioned one-to-many link relation attribute in the Mesh model.

Parameters

target – Mesh one-to-many versioned link relation attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
new_entries – the list of lists of link relation versions to insert. The first level list represents entries. Each entry can have multiple link relation versions.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

async update_versioned_one_to_one_link_relation_attribute(target: Union[UUID, str, AttributeBase], start_time: datetime, end_time: datetime, new_versions: List[LinkRelationVersion]) → None[source]¶

Update an existing Mesh versioned one-to-one link relation attribute in the Mesh model.

Parameters

target – Mesh one-to-one versioned link relation attribute to be updated. It could be a Universal Unique Identifier or a path in the Mesh model. See: objects and attributes paths.
start_time – the (inclusive) start of the edit interval.
end_time – the (exclusive) end of the edit interval.
new_versions – the list of link relation versions to insert. All versions must be within [start_time, end_time) interval.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed.

See also

async update_xy_sets(target: Union[UUID, str, AttributeBase], start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, new_xy_sets: List[XySet] = []) → None[source]¶

Replace XY sets on an XY-set attribute on the server.

An XY-set attribute is either versioned, with a kind XYZSeriesAttribute, or unversioned, with a kind XYSetAttribute.

When applied to an unversioned attribute the update_xy_sets operation removes the existing XY-set, and replaces it with the contents of xy_sets, which must contain zero or one XY-set.

When applied to a versioned attribute the operation deletes all versions in the interval [start_time, end_time), and inserts the new versions in xy_sets.

Parameters

target – the GUID or the path of an XY-set attribute.
start_time – the (inclusive) start of the edit interval. Must be None for unversioned XY-set attributes.
end_time – the (exclusive) end of the edit interval. Must be None for unversioned XY-set attributes.
new_xy_sets – the list of XY-sets to insert. Must contain zero or one element for unversioned attributes. All elements must be within [start_time, end_time) for versioned attributes.

Raises

grpc.RpcError – Error message raised if the gRPC request could not be completed
TypeError – on invalid arguments (see above).

See also