utspclient package

Subpackages

Helpers for common Providers

Submodules

utspclient.client module

Functions for sending calculation requests to the UTSP and retrieving results.

utspclient.client.build_url(address: str, route: str) → str

Helper function to build a URL

Parameters:

address – server address
route – URL route

Returns:

the full URL

utspclient.client.calculate_multiple_requests(address: str, requests: Iterable[str | TimeSeriesRequest], api_key: str = '', raise_exceptions: bool = True, quiet: bool = False, timeout: float = 10) → List[ResultDelivery | Exception]

Sends multiple calculation requests to the UTSP and collects the results. The requests can be calculated in parallel.

Parameters:

address – address of the UTSP server
requests – The request objects to send
api_key – API key for accessing the UTSP, defaults to “”
raise_exceptions – if True, failed requests raise exceptions, otherwhise the exception object is added to the result list; defaults to True
quiet – whether no console outputs should be produced, defaults to False
timeout – the time in seconds to wait between repeated requests to check the calculation status

Returns:

a list containing the requested result objects; if raise_exceptions was set to False, this list can also contain exceptions

utspclient.client.decompress_result_data(result: EncodedResultDelivery) → ResultDelivery

Decodes and decompresses the result data returned from the UTSP.

Parameters:: data – encoded and compressed result data
Returns:: usable result data

utspclient.client.get_result(reply: RestReply) → ResultDelivery | None

Helper function for getting a time series out of a rest reply if it was delivered. Raises an exception if the calculation failed

Parameters:: reply (RestReply) – the reply from the utsp server to check for a time series
Raises:: Exception – if the calculation failed
Returns:: the delivered time series, or None
Return type:: Optional[TimeSeriesDelivery]

utspclient.client.is_finished(status: CalculationStatus) → bool

Checks whether the request with the specified status is finished (successful or failed) or whether it is still in calculation.

Parameters:: status (CalculationStatus) – the status of the request
Returns:: _description_
Return type:: bool

utspclient.client.request_time_series_and_wait_for_delivery(address: str, request: str | TimeSeriesRequest, api_key: str = '', quiet: bool = False, timeout: float = 10) → ResultDelivery

Requests a single time series from the UTSP server from the specified time series provider.

Parameters:

address – address of the UTSP server
request – The request object defining the requested time series
api_key – API key for accessing the UTSP, defaults to “”
quiet – whether no console outputs should be produced, defaults to False
timeout – the time in seconds to wait between repeated requests to check the calculation status

Returns:

The requested result data

utspclient.client.send_request(url: str, request: str | TimeSeriesRequest, api_key: str = '') → RestReply

Sends the request to the utsp and returns the reply

Parameters:

url (str) – URL of the utsp server endpoint
request (Union[str, TimeSeriesRequest]) – the request to send
api_key (str, optional) – the api key to use, defaults to “”

Raises:

Exception – if the server reported an error

Returns:

the reply from the utsp server

Return type:

RestReply

utspclient.client.shutdown(address: str, api_key: str = '')

Shuts down all UTSP workers connected to the server.

Parameters:

address – address of the UTSP server
api_key (str, optional) – API key for accessing the UTSP, defaults to “”

utspclient.client.upload_provider_build_context(address: str, api_key: str, path: str, versioned_name: str)

Uploads an image build context for a provider. A build context is a .tar or .tar.gz file containing everything that is necessary for building the provider image. The image will then be built by the UTSP server.

Parameters:

address – address of the UTSP server to add the provider to
api_key – API key for accessing the UTSP server
path – path of the build context file
versioned_name – versioned name of the provider

utspclient.datastructures module

Common data structures for communication between the UTSP server and the client.

class utspclient.datastructures.CalculationStatus(value)

Bases: Enum

Indicates the current state of a request

CALCULATIONFAILED = 4

CALCULATIONSTARTED = 3

INCALCULATION = 1

INDATABASE = 2

UNKNOWN = 0

class utspclient.datastructures.EncodedResultDelivery(original_request: ~utspclient.datastructures.TimeSeriesRequest, data: dict[str, str] = <factory>, is_compressed: bool = False)

Bases: ResultDeliveryBase

Contains encoded result data for a singe request. Can be decoded back to a ResultDelivery object.

data: dict[str, str]: name and content of all result files

decode_data() → ResultDelivery: Decode the base64-encoded data

classmethod from_dict(kvs: dict | list | str | int | float | bool | None, *, infer_missing=False) → A

classmethod from_json(s: str | bytes | bytearray, *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw) → A

is_compressed: bool = False

classmethod schema(*, infer_missing: bool = False, only=None, exclude=(), many: bool = False, context=None, load_only=(), dump_only=(), partial: bool = False, unknown=None) → SchemaF[A]

to_dict(encode_json=False) → Dict[str, dict | list | str | int | float | bool | None]

to_json(*, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, indent: str | int | None = None, separators: Tuple[str, str] | None = None, default: Callable | None = None, sort_keys: bool = False, **kw) → str

class utspclient.datastructures.RestReply(result_delivery: EncodedResultDelivery | None = None, status: CalculationStatus = CalculationStatus.UNKNOWN, request_hash: str = '', info: str | None = None)

Bases: object

Reply from the UTSP server to a single request. Contains all available information about the request.

classmethod from_dict(kvs: dict | list | str | int | float | bool | None, *, infer_missing=False) → A

classmethod from_json(s: str | bytes | bytearray, *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw) → A

info: str | None = None: optional information, or an error message if the request failed

request_hash: str = '': hash of the original request which this reply belongs to

result_delivery: EncodedResultDelivery | None = None: compressed result data, if the request finished without an error

classmethod schema(*, infer_missing: bool = False, only=None, exclude=(), many: bool = False, context=None, load_only=(), dump_only=(), partial: bool = False, unknown=None) → SchemaF[A]

status: CalculationStatus = 0: current status of the request

to_dict(encode_json=False) → Dict[str, dict | list | str | int | float | bool | None]

to_json(*, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, indent: str | int | None = None, separators: Tuple[str, str] | None = None, default: Callable | None = None, sort_keys: bool = False, **kw) → str

class utspclient.datastructures.ResultDelivery(original_request: ~utspclient.datastructures.TimeSeriesRequest, data: dict[str, bytes] = <factory>, is_compressed: bool = False)

Bases: ResultDeliveryBase

Contains the results for a singe request. Can compress/decompress the result file contents to reduce size. Should not be serialized to json due to the bytes in the data member. For that purpose, the object can be encoded to a EncodedResultDelivery object first.

compress_data(): Compresses the data to use less storage

data: dict[str, bytes]: name and content of all result files

decompress_data(): Decompresses the data.

encode_data(): base64-encode the data for conversion to json.

is_compressed: bool = False

class utspclient.datastructures.ResultDeliveryBase(original_request: ~utspclient.datastructures.TimeSeriesRequest, data: dict = <factory>)

Bases: ABC

Base class for the results for a singe request.

data: dict: name and content of all result files

get_file_count() → int

Returns the number of contained files.

Returns:: number of files

original_request: TimeSeriesRequest: the original request the results belong to

size_in_gb() → float

Returns the total size of the result data in gigabytes.

Returns:: size in gigabytes

class utspclient.datastructures.ResultFileRequirement(value)

Bases: Enum

Determines whether specified result files are required or optional. Only when a required file is not created by the provider an error is raised.

OPTIONAL = 1

REQUIRED = 0

class utspclient.datastructures.TimeSeriesRequest(simulation_config: str, providername: str, guid: str = '', required_result_files: ~typing.Dict[str, ~utspclient.datastructures.ResultFileRequirement | None] = <factory>, input_files: ~typing.Dict[str, str] = <factory>)

Bases: object

Contains all necessary information for a calculation request. It also functions as an identifier for the request, so sending the same object again will always return the same results.

classmethod from_dict(kvs: dict | list | str | int | float | bool | None, *, infer_missing=False) → A

classmethod from_json(s: str | bytes | bytearray, *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw) → A

get_hash() → str

Calculates a hash for this object. This is used to distinguish different requests.

Returns:: the hash of this object
Return type:: str

guid: str = '': optional unique identifier, can be used to force recalculation of otherwhise identical requests

input_files: Dict[str, str]: Names and contents of additional input files to be created in the provider container, if required. For internal reasons the ‘bytes’ type cannot be used here, so the file contents are stored base64-encoded.

providername: str: the provider which shall process the request

required_result_files: Dict[str, ResultFileRequirement | None]: Desired files created by the provider that are sent back as result. Throws an error if one of these files is not created. If left empty all created files are returned.

classmethod schema(*, infer_missing: bool = False, only=None, exclude=(), many: bool = False, context=None, load_only=(), dump_only=(), partial: bool = False, unknown=None) → SchemaF[A]

simulation_config: str: provider-specific string defining the requested results

to_dict(encode_json=False) → Dict[str, dict | list | str | int | float | bool | None]

to_json(*, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, indent: str | int | None = None, separators: Tuple[str, str] | None = None, default: Callable | None = None, sort_keys: bool = False, **kw) → str

utspclient.result_file_filters module

This module defines relevant output files for typical use cases to avoid transmitting and storing unneeded files

class utspclient.result_file_filters.HiSimFilters

Bases: object

RESIDENCE_BUILDING = 'Residence_Building.csv'

class utspclient.result_file_filters.LPGFilters

Bases: object

Provides result file names for the LPG

class BodilyActivity

Bases: object

Result file names for bodily activity

HIGH = 'Results/BodilyActivityLevel.High.HH1.json'

LOW = 'Results/BodilyActivityLevel.Low.HH1.json'

OUTSIDE = 'Results/BodilyActivityLevel.Outside.HH1.json'

UNKNOWN = 'Results/BodilyActivityLevel.Unknown.HH1.json'

FLEXIBILITY_EVENTS = 'Reports/FlexibilityEvents.HH1.json'

static all_car_locations_optional() → Dict[str, ResultFileRequirement]: Helper function to get any created car location file.

static all_car_states_optional() → Dict[str, ResultFileRequirement]: Helper function to get any created car state file.

static all_driving_distances_optional() → Dict[str, ResultFileRequirement]: Helper function to get any created driving distance file.

static car_location(car: JsonReference | str) → str: Result file names for car locations

static car_state(car: JsonReference | str) → str: Result file names for car states

static driving_distance(car: JsonReference | str) → str: Result file names for driving distances

static sum_hh1(load_type: str, json: bool = False, no_flex: bool = False) → str: Returns the file name of the sum load profile for the first simulated household, for the specified load type

static sum_hh1_ext_res(load_type: str, resolution_in_s: int, json: bool = False) → str: Returns the file name of the sum load profile for the first simulated household, for the specified load type, in the external resolution. The resolution specified here must match the external resolution specified in the LPG request.

utspclient package

Subpackages

Submodules

utspclient.client module

utspclient.datastructures module

utspclient.result_file_filters module

Module contents