eta_utility.eta_x.envs.state module

class eta_utility.eta_x.envs.state.StateVar(name: str, *, is_agent_action=False, is_agent_observation=False, add_to_state_log=True, ext_id: str | int | None = None, is_ext_input=False, is_ext_output=False, ext_scale_add=0, ext_scale_mult=1, interact_id: int | None = None, from_interact=False, interact_scale_add=0, interact_scale_mult=1, scenario_id: str | None = None, from_scenario=False, scenario_scale_add=0, scenario_scale_mult=1, low_value=nan, high_value=nan, abort_condition_min=None, abort_condition_max=None, index=0)

Bases: object

A variable in the state of an environment.

name: str

Name of the state variable (This must always be specified).

is_agent_action: bool

Should the agent specify actions for this variable? (default: False).

is_agent_observation: bool

Should the agent be allowed to observe the value of this variable? (default: False).

add_to_state_log: bool

Should the state log of this episode be added to state_log_longtime? (default: True).

ext_id: str | int | None

Name or identifier (order) of the variable in the external interaction model (e.g.: environment or FMU) (default: StateVar.name if (is_ext_input or is_ext_output) else None).

is_ext_input: bool

Should this variable be passed to the external model as an input? (default: False).

is_ext_output: bool

Should this variable be parsed from the external model output? (default: False).

ext_scale_add: float

Value to add to the output from an external model (default: 0).

ext_scale_mult: float

Value to multiply to the output from an external model (default: 1).

interact_id: int | None

Name or identifier (order) of the variable in an interaction environment (default: None).

from_interact: bool

Should this variable be read from the interaction environment? (default: False).

interact_scale_add: float

Value to add to the value read from an interaction (default: 0).

interact_scale_mult: float

Value to multiply to the value read from an interaction (default: 1).

scenario_id: str | None

Name of the scenario variable, this value should be read from (default: None).

from_scenario: bool

Should this variable be read from imported timeseries date? (default: False).

scenario_scale_add: float

Value to add to the value read from a scenario file (default: 0).

scenario_scale_mult: float

Value to multiply to the value read from a scenario file (default: 1).

low_value: float

Lowest possible value of the state variable (default: np.nan).

high_value: float

Highest possible value of the state variable (default: np.nan).

abort_condition_min: float | None

If the value of the variable dips below this, the episode should be aborted (default: None).

abort_condition_max: float | None

If the value of the variable rises above this, the episode should be aborted (default: None).

index: int

Determine the index, where to look (useful for mathematical optimization, where multiple time steps could be returned). In this case, the index values might be different for actions and observations.

classmethod from_dict(mapping: Mapping[str, Any] | pd.Series) → StateVar

Initialize a state var from a dictionary or pandas Series.

Parameters:

mapping – dictionary or pandas Series to initialize from.

Returns:

Initialized StateVar object

class eta_utility.eta_x.envs.state.StateConfig(*state_vars: StateVar)

Bases: object

The configuration for the action and observation spaces. The values are used to control which variables are part of the action space and observation space. Additionally, the parameters can specify abort conditions and the handling of values from interaction environments or from simulation. Therefore, the StateConfig is very important for the functionality of ETA X.

vars: dict[str, StateVar]

Mapping of the variables names to their StateVar instance with all associated information.

actions: list[str]

List of variables that are agent actions.

observations: list[str]

List of variables that are agent observations.

add_to_state_log: set[str]

Set of variables that should be logged.

ext_inputs: list[str]

List of variables that should be provided to an external source (such as an FMU).

ext_outputs: list[str]

List of variables that can be received from an external source (such as an FMU).

map_ext_ids: dict[str, str | int]

Mapping of variable names to their external IDs.

rev_ext_ids: dict[str | int, str]

Reverse mapping of external IDs to their corresponding variable names.

ext_scale: dict[str, dict[str, float]]

Dictionary of scaling values for external input values (for example from simulations). Contains fields ‘add’ and ‘multiply’

interact_outputs: list[str]

List of variables that should be read from an interaction environment.

map_interact_ids: dict[str, int]

Mapping of internal environment names to interact IDs.

interact_scale: dict[str, dict[str, float]]

Dictionary of scaling values for interact values. Contains fields ‘add’ and ‘multiply’.

scenarios: list[str]

List of variables which are loaded from scenario files.

map_scenario_ids: dict[str, str]

Mapping of internal environment names to scenario IDs.

scenario_scale: dict[str, dict[str, float]]

Dictionary of scaling values for scenario values. Contains fields ‘add’ and ‘multiply’.

abort_conditions_min: list[str]

List of variables that have minimum values for an abort condition.

abort_conditions_max: list[str]

List of variables that have maximum values for an abort condition.

classmethod from_dict(mapping: Sequence[Mapping[str, Any]] | pd.DataFrame) → StateConfig

This will convert a potentially incomplete StateConfig DataFrame or a list of dictionaries to the standardized StateConfig format. This will ignore any additional columns.

Parameters:

mapping – Mapping to be converted to the StateConfig format.

Returns:

StateConfig object.

append_state(var: StateVar) → None

Append a state variable to the state configuration.

Parameters:

var – StateVar instance to append to the configuration.

store_file(file: Path) → None

Save the StateConfig to a comma separated file.

Parameters:

file – Path to the file.

within_abort_conditions(state: Mapping[str, float]) → bool

Check whether the given state is within the abort conditions specified by the StateConfig instance.

Parameters:

state – The state array to check for conformance.

Returns:

Result of the check (False if the state does not conform to the required conditions).

continuous_action_space() → Box

Generate an action space according to the format required by the OpenAI specification.

Returns:

Action space.

continuous_obs_space() → Box

Generate a continuous observation space according to the format required by the OpenAI specification.

Returns:

Observation Space.

continuous_observation_space() → Box

continuous_spaces() → tuple[Box, Box]

Generate continuous action and observation spaces according to the OpenAI specification.

Returns:

Tuple of action space and observation space.

property loc: dict[str, StateVar]

Behave like dataframe (enable indexing via loc) for compatibility.