Source code for grid2op.Action.actionSpace

# Copyright (c) 2019-2020, RTE (
# See AUTHORS.txt
# This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
# If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
# you can obtain one at
# SPDX-License-Identifier: MPL-2.0
# This file is part of Grid2Op, Grid2Op a testbed platform to model sequential decision making in power systems.

import warnings
import copy
from typing import Dict, List, Any, Literal

from grid2op.Action.baseAction import BaseAction
from grid2op.Action.serializableActionSpace import SerializableActionSpace

[docs]class ActionSpace(SerializableActionSpace): """ :class:`ActionSpace` should be created by an :class:`grid2op.Environment.Environment` with its parameters coming from a properly set up :class:`grid2op.Backend.Backend` (ie a Backend instance with a loaded powergrid. See :func:`grid2op.Backend.Backend.load_grid` for more information). It will allow, thanks to its :func:`ActionSpace.__call__` method to create valid :class:`BaseAction`. It is the the preferred way to create an object of class :class:`BaseAction` in this package. On the contrary to the :class:`BaseAction`, it is NOT recommended to overload this helper. If more flexibility is needed on the type of :class:`BaseAction` created, it is recommended to pass a different "*actionClass*" argument when it's built. Note that it's mandatory that the class used in the "*actionClass*" argument derived from the :class:`BaseAction`. Attributes ---------- legal_action: :class:`grid2op.RulesChecker.BaseRules` Class specifying the rules of the game used to check the legality of the actions. """
[docs] def __init__( self, gridobj, legal_action, actionClass=BaseAction, # need to be a base grid2op type (and not a type generated on the fly) ): """ INTERNAL USE ONLY .. warning:: /!\\\\ Internal, do not use unless you know what you are doing /!\\\\ The actions space is created by the environment. Do not attempt to create one yourself. All parameters (name_gen, name_load, name_line, sub_info, etc.) are used to fill the attributes having the same name. See :class:`ActionSpace` for more information. Parameters ---------- gridobj: :class:`grid2op.Space.GridObjects` The representation of the powergrid. actionClass: ``type`` Note that this parameter expected a class and not an object of the class. It is used to return the appropriate action type. legal_action: :class:`grid2op.RulesChecker.BaseRules` Class specifying the rules of the game used to check the legality of the actions. """ actionClass._add_shunt_data() actionClass._update_value_set() SerializableActionSpace.__init__(self, gridobj, actionClass=actionClass) self.legal_action = legal_action
[docs] def __call__( self, dict_: Dict[Literal["injection", "hazards", "maintenance", "set_line_status", "change_line_status", "set_bus", "change_bus", "redispatch", "set_storage", "curtail", "raise_alarm", "raise_alert"], Any] = None, check_legal: bool = False, env: "grid2op.Environment.BaseEnv" = None, *, injection=None, ) -> BaseAction: """ This utility allows you to build a valid action, with the proper sizes if you provide it with a valid dictionary. More information about this dictionary can be found in the :func:`Action.update` help. This dictionary is not changed in this method. **NB** This is the only recommended way to make a valid, with proper dimension :class:`Action` object: Examples -------- Here is a short example on how to make a action. For more detailed examples see :func:`Action.update` .. code-block:: python import grid2op # create a simple environment env = grid2op.make("l2rpn_case14_sandbox") act = env.action_space({}) # act is now the "do nothing" action, that doesn't modify the grid. Parameters ---------- dict_ : ``dict`` see :func:`Action.__call__` documentation for an extensive help about this parameter check_legal: ``bool`` is there a test performed on the legality of the action. **NB** When an object of class :class:`Action` is used, it is automatically tested for ambiguity. If this parameter is set to ``True`` then a legality test is performed. An action can be illegal if the environment doesn't allow it, for example if an agent tries to reconnect a powerline during a maintenance. env: :class:`grid2op.Environment.Environment`, optional An environment used to perform a legality check. Returns ------- res: :class:`BaseAction` An action that is valid and corresponds to what the agent want to do with the formalism defined in see :func:`Action.udpate`. """ # build the action res = self.actionClass() # update the action res.update(dict_) if check_legal: is_legal, reason = self._is_legal(res, env) if not is_legal: raise reason return res
[docs] def _custom_deepcopy_for_copy(self, new_obj): """implements a faster "res = copy.deepcopy(self)" to use in "self.copy" Do not use it anywhere else... """ # TODO clean that after it is working... (ie make this method per class...) # fill the super classes super()._custom_deepcopy_for_copy(new_obj) # now fill my class new_obj.legal_action = copy.deepcopy(self.legal_action)
[docs] def copy(self): """ INTERNAL .. warning:: /!\\\\ Internal, do not use unless you know what you are doing /!\\\\ Perform a deep copy of the Observation space. """ # performs the copy # res = copy.deepcopy(self) # painfully slow... # create an empty "me" my_cls = type(self) res = my_cls.__new__(my_cls) self._custom_deepcopy_for_copy(res) return res
[docs] def close(self): """ INTERNAL .. warning:: /!\\\\ Internal, do not use unless you know what you are doing /!\\\\ Make sure all references to possible backends are closed. This is not used here in general but might be for some specific cases. """ pass