eta_ctrl.envs.state module

class eta_ctrl.envs.state.StateVar(*, name: str, is_agent_action: bool = False, is_agent_observation: bool = False, add_to_state_log: bool = True, ext_id: str | None = None, is_ext_input: bool = False, is_ext_output: bool = False, ext_scale_add: float = 0.0, ext_scale_mult: float = 1.0, scenario_id: str | None = None, from_scenario: bool = False, scenario_scale_add: float = 0.0, scenario_scale_mult: float = 1.0, low_value: float = -3.4028234663852886e+38, high_value: float = 3.4028234663852886e+38, abort_condition_min: float = -inf, abort_condition_max: float = inf, index: int = 0, duration: int = 1)

Bases: BaseModel

A variable in the state of an environment.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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 | None

Name of the variable in the external 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.0).

ext_scale_mult: float

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

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.0).

scenario_scale_mult: float

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

low_value: float

Lowest possible value of the state variable (default: -np.finfo(np.float32).max).

high_value: float

Highest possible value of the state variable (default: np.finfo(np.float32).max).

abort_condition_min: float

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

abort_condition_max: float

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

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.

duration: int

For scenario StateVars: Length of StateVars horizon in state, e.g. the prediction horizon length (unit: steps).

model_post_init(context: Any) → None

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

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_ctrl.envs.state.StateStructure(*, state_parameters: dict[str, float | bool] | None = None, actions: list[StateVar], observations: list[StateVar])

Bases: BaseModel

Used for parsing the state structure from a config file.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

state_parameters: dict[str, float | bool] | None

actions: list[StateVar]

observations: list[StateVar]

class eta_ctrl.envs.state.StateConfig(*state_vars: StateVar, source_file: Path | None = None)

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. Therefore, the StateConfig is very important for the functionality of EtaCtrl.

vars

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

source_file: Path | None

Attribute to store the source file path (if loaded from file).

df_vars: pandas.DataFrame

actions: list[str]

List of variables that are agent actions. Needs to be ordered.

observations: list[str]

Set of variables that are agent observations.

add_to_state_log: list[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]

Mapping of variable names to their external IDs.

rev_ext_ids: dict[str, str]

Reverse mapping of external IDs to their corresponding variable names.

scenario_outputs: 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.

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_file(root_path: pathlib.Path, filename: Path, extra_params: Mapping[str, float] | None = None) → Self

Load a StateConfig from a config file.

Parameters:

file – Path of the config file.

Returns:

StateConfig object.

classmethod from_dict(mapping: Sequence[dict[str, Any]] | pd.DataFrame, *, state_params: Mapping[str, float] | None = None, **kwargs: Any) → Self

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.

• state_params – State parameter values for parameters supplied in mapping (e.g. {min_temp: 20})

Returns:

StateConfig object.

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 a numpy ndarray action space.

Returns:

Action space.

continuous_observation_space() → Dict

Generate a dictionary observation space.

Returns:

Observation Space.

continuous_spaces() → tuple[Box, Dict]

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

Returns:

Tuple of action space and observation space.

property loc: pandas.api.indexers._LocIndexer

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