bluemira.utilities.opt_variables
================================

.. py:module:: bluemira.utilities.opt_variables

.. autoapi-nested-parse::

   Optimisation variable class.



Attributes
----------

.. autoapisummary::

   bluemira.utilities.opt_variables.VarDictT


Classes
-------

.. autoapisummary::

   bluemira.utilities.opt_variables.OptVarVarDictValueT
   bluemira.utilities.opt_variables.OptVarDictT
   bluemira.utilities.opt_variables.OptVarSerialisedT
   bluemira.utilities.opt_variables.OptVariable
   bluemira.utilities.opt_variables.OptVariablesFrame


Functions
---------

.. autoapisummary::

   bluemira.utilities.opt_variables.ov


Module Contents
---------------

.. py:class:: OptVarVarDictValueT

   Bases: :py:obj:`TypedDict`

   .. autoapi-inheritance-diagram:: bluemira.utilities.opt_variables.OptVarVarDictValueT
      :parts: 1
      :private-bases:


   Typed dictionary for a the values of an OptVariable from a var_dict.


   .. py:attribute:: value
      :type:  float


   .. py:attribute:: lower_bound
      :type:  NotRequired[float]


   .. py:attribute:: upper_bound
      :type:  NotRequired[float]


   .. py:attribute:: fixed
      :type:  NotRequired[bool]


.. py:data:: VarDictT

.. py:class:: OptVarDictT

   Bases: :py:obj:`TypedDict`

   .. autoapi-inheritance-diagram:: bluemira.utilities.opt_variables.OptVarDictT
      :parts: 1
      :private-bases:


   Typed dictionary representation of an OptVariable.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: value
      :type:  float


   .. py:attribute:: lower_bound
      :type:  float


   .. py:attribute:: upper_bound
      :type:  float


   .. py:attribute:: fixed
      :type:  bool


   .. py:attribute:: description
      :type:  str


.. py:class:: OptVarSerialisedT

   Bases: :py:obj:`TypedDict`

   .. autoapi-inheritance-diagram:: bluemira.utilities.opt_variables.OptVarSerialisedT
      :parts: 1
      :private-bases:


   Typed dictionary for a serialised OptVariable.


   .. py:attribute:: value
      :type:  float


   .. py:attribute:: lower_bound
      :type:  float


   .. py:attribute:: upper_bound
      :type:  float


   .. py:attribute:: fixed
      :type:  bool


   .. py:attribute:: description
      :type:  str


.. py:class:: OptVariable(name: str, value: float, lower_bound: float, upper_bound: float, *, fixed: bool = False, description: str | None = None)

   A bounded variable, uniformly normalised from 0 to 1 w.r.t. its bounds.

   :param name: Name of the variable
   :param value: Value of the variable
   :type value: float
   :param lower_bound: Lower bound of the variable
   :param upper_bound: Upper bound of the variable
   :param fixed: Whether or not the variable is to be held constant
   :param description: Description of the variable


   .. py:attribute:: __slots__
      :value: ('_value', 'description', 'fixed', 'lower_bound', 'name', 'upper_bound')



   .. py:attribute:: name


   .. py:attribute:: _value


   .. py:attribute:: lower_bound


   .. py:attribute:: upper_bound


   .. py:attribute:: fixed
      :value: False



   .. py:attribute:: description
      :value: None



   .. py:property:: value
      :type: float


      The value of the variable.


   .. py:property:: normalised_value
      :type: float


      The value uniformly normalised between 0 and 1 w.r.t. its bounds


   .. py:method:: from_normalised(norm: float) -> float

      The value from a normalised value between [0 -> 1], w.r.t its bounds

      :returns: The unnormalised value



   .. py:method:: fix(value: float | None = None)

      Fix the variable at a specified value. Ignores bounds.

      :param value: Value at which to fix the variable.



   .. py:method:: adjust(value: float | None = None, lower_bound: float | None = None, upper_bound: float | None = None, *, strict_bounds: bool = True)

      Adjust the OptVariable.

      :param value: Value of the variable to set
      :param lower_bound: Value of the lower bound to set
      :param upper_bound: Value of the upper to set
      :param strict_bounds: If True, will raise errors if values are outside the bounds. If False, the
                            bounds are dynamically adjusted to match the value.

      :raises OptVariablesError: OptVariable is fixed



   .. py:method:: as_dict() -> OptVarDictT

      :returns: Dictionary representation of OptVariable, can be used for serialisation



   .. py:method:: as_serialisable() -> OptVarSerialisedT

      :returns: Dictionary representation of OptVariable



   .. py:method:: from_serialised(name: str, data: OptVarSerialisedT) -> OptVariable
      :classmethod:


      :returns: Create an OptVariable from a dictionary



   .. py:method:: _adjust_bounds_to(value)

      Adjust the bounds to the value



   .. py:method:: _validate_bounds()


   .. py:method:: _validate_value(value)


   .. py:method:: __repr__() -> str

      :returns: Representation of OptVariable



   .. py:method:: __str__() -> str

      :returns: Pretty representation of OptVariable



   .. py:method:: __add__(other: OptVariable)

      :returns: The sum of two OptVariables as the sum of their values

      :raises TypeError: Cannot perform operation on value



   .. py:method:: __sub__(other: OptVariable)

      :returns: The subtraction of two OptVariables as the subtraction of their values

      :raises TypeError: Cannot perform operation on value



   .. py:method:: __mul__(other: OptVariable)

      :returns: The multiplication of two OptVariables as the multiplication of their values

      :raises TypeError: Cannot perform operation on value



.. py:function:: ov(name: str, value: float, lower_bound: float, upper_bound: float, *, fixed: bool = False, description: str | None = None) -> dataclasses.field

   Field factory for OptVariable

   :returns: Field wrapped OptVariable


.. py:class:: OptVariablesFrame

   Class to model the variables for an optimisation


   .. py:method:: __iter__() -> collections.abc.Iterator[OptVariable]

      Iterate over this frame's parameters.

      The order is based on the order in which the parameters were
      declared.

      :Yields: Each optimisation variable



   .. py:method:: __getitem__(name: str) -> OptVariable

      Dictionary-like access to variables.

      :param name: Name of the variable to get

      :returns: The opt variable



   .. py:method:: adjust_variable(name: str, value: float | None = None, lower_bound: float | None = None, upper_bound: float | None = None, *, fixed: bool = False, strict_bounds: bool = True)

      Adjust a variable in the frame.

      :param name: Name of the variable to adjust
      :param value: Value of the variable to set
      :param lower_bound: Value of the lower bound to set
      :param upper_bound: Value of the upper to set
      :param fixed: Whether or not the variable is to be held constant
      :param strict_bounds: If True, will raise errors if values are outside the bounds. If False, the
                            bounds are dynamically adjusted to match the value.
      :type strict_bounds: bool



   .. py:method:: adjust_variables(var_dict: VarDictT | None = None, *, strict_bounds=True)

      Adjust multiple variables in the frame.

      :param var_dict: Dictionary with which to update the set, of the form
                       {"var_name": {"value": v, "lower_bound": lb, "upper_bound": ub}, ...}
      :param strict_bounds: If True, will raise errors if values are outside the bounds. If False, the
                            bounds are dynamically adjusted to match the value.
      :type strict_bounds: bool

      :raises OptVariablesError: var_dict structure not correct



   .. py:method:: fix_variable(name: str, value: float | None = None)

      Fix a variable in the frame, removing it from optimisation but preserving a
      constant value.

      :param name: Name of the variable to fix
      :param value: Value at which to fix the variable (will default to present value)



   .. py:method:: get_normalised_values() -> numpy.typing.NDArray[numpy.float64]

      Get the normalised values of all free variables.

      :returns: **x_norm** -- Array of normalised values
      :rtype: np.ndarray



   .. py:method:: set_values_from_norm(x_norm)

      Set values from a normalised vector.

      :param x_norm: Array of normalised values
      :type x_norm: np.ndarray



   .. py:method:: get_values_from_norm(x_norm: numpy.typing.NDArray[numpy.float64]) -> list[float]

      Get actual values from a normalised vector.

      :param x_norm: Array of normalised values
      :type x_norm: np.ndarray

      :returns: **x_true** -- Array of actual values in units
      :rtype: np.ndarray

      :raises OptVariablesError: Number of free variables is not equal to the size of x_norm



   .. py:property:: names

      All variable names of the variable set.


   .. py:property:: values

      All un-normalised values of the variable set (including fixed variable values).


   .. py:property:: n_free_variables
      :type: int


      Number of free variables in the set.


   .. py:property:: _opt_vars


   .. py:property:: _fixed_vars


   .. py:property:: _fixed_variable_indices
      :type: list


      Indices of fixed variables in the set.


   .. py:method:: as_dict() -> dict[str, OptVarDictT]

      :returns: Dictionary Representation of the frame



   .. py:method:: as_serialisable() -> dict[str, OptVarSerialisedT]

      :returns: Serialised Representation of the frame



   .. py:method:: to_json(file: str, **kwargs)

      Save the OptVariablesFrame to a json file.

      :param path: Path to save the json file to.
      :type path: str



   .. py:method:: from_json(file: pathlib.Path | str | TextIO) -> OptVariablesFrame
      :classmethod:


      Create an OptVariablesFrame instance from a json file.

      :param file: The path to the file, or an open file handle that supports reading.
      :type file: Union[str, TextIO]

      :returns: The new instance



   .. py:method:: tabulate(tablefmt: str = 'fancy_grid') -> str

      Tabulate OptVariablesFrame

      :param tablefmt: The format of the table - see
                       https://github.com/astanin/python-tabulate#table-format

      :returns: The tabulated data
      :rtype: tabulated



   .. py:method:: __str__() -> str

      :returns: A pretty representation of the OptVariablesFrame inside the console



   .. py:method:: __repr__() -> str

      :returns: A representation of the OptVariablesFrame inside the console