bluemira.utilities.opt_variables

Optimisation variable class.

Attributes

VarDictT

Classes

OptVarVarDictValueT

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

OptVarDictT

Typed dictionary representation of an OptVariable.

OptVarSerialisedT

Typed dictionary for a serialised OptVariable.

OptVariable

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

OptVariablesFrame

Class to model the variables for an optimisation

Functions

ov(→ dataclasses.field)

Field factory for OptVariable

Module Contents

class bluemira.utilities.opt_variables.OptVarVarDictValueT

Bases: TypedDict

Inheritance diagram of bluemira.utilities.opt_variables.OptVarVarDictValueT

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

value: float
lower_bound: NotRequired[float]
upper_bound: NotRequired[float]
fixed: NotRequired[bool]
bluemira.utilities.opt_variables.VarDictT
class bluemira.utilities.opt_variables.OptVarDictT

Bases: TypedDict

Inheritance diagram of bluemira.utilities.opt_variables.OptVarDictT

Typed dictionary representation of an OptVariable.

name: str
value: float
lower_bound: float
upper_bound: float
fixed: bool
description: str
class bluemira.utilities.opt_variables.OptVarSerialisedT

Bases: TypedDict

Inheritance diagram of bluemira.utilities.opt_variables.OptVarSerialisedT

Typed dictionary for a serialised OptVariable.

value: float
lower_bound: float
upper_bound: float
fixed: bool
description: str
class bluemira.utilities.opt_variables.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.

Parameters:

  • name (str) – Name of the variable

  • value (float) – Value of the variable

  • lower_bound (float) – Lower bound of the variable

  • upper_bound (float) – Upper bound of the variable

  • fixed (bool) – Whether or not the variable is to be held constant

  • description (str | None) – Description of the variable

__slots__ = ('_value', 'description', 'fixed', 'lower_bound', 'name', 'upper_bound')
name
_value
lower_bound
upper_bound
fixed = False
description = None
property value: float

The value of the variable.

Return type:

float

property normalised_value: float

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

Return type:

float

from_normalised(norm: float) → float

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

Returns:

The unnormalised value

Parameters:

norm (float)

Return type:

float

fix(value: float | None = None)

Fix the variable at a specified value. Ignores bounds.

Parameters:

value (float | None) – Value at which to fix the variable.

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

Adjust the OptVariable.

Parameters:

  • value (float | None) – Value of the variable to set

  • lower_bound (float | None) – Value of the lower bound to set

  • upper_bound (float | None) – Value of the upper to set

  • strict_bounds (bool) – 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

as_dict() → OptVarDictT
Returns:

Dictionary representation of OptVariable, can be used for serialisation

Return type:

OptVarDictT

as_serialisable() → OptVarSerialisedT
Returns:

Dictionary representation of OptVariable

Return type:

OptVarSerialisedT

classmethod from_serialised(name: str, data: OptVarSerialisedT) → OptVariable
Returns:

Create an OptVariable from a dictionary

Parameters:
Return type:

OptVariable

_adjust_bounds_to(value)

Adjust the bounds to the value

_validate_bounds()
_validate_value(value)
__repr__() → str
Returns:

Representation of OptVariable

Return type:

str

__str__() → str
Returns:

Pretty representation of OptVariable

Return type:

str

__add__(other: OptVariable)
Returns:

The sum of two OptVariables as the sum of their values

Raises:

TypeError – Cannot perform operation on value

Parameters:

other (OptVariable)

__sub__(other: OptVariable)
Returns:

The subtraction of two OptVariables as the subtraction of their values

Raises:

TypeError – Cannot perform operation on value

Parameters:

other (OptVariable)

__mul__(other: OptVariable)
Returns:

The multiplication of two OptVariables as the multiplication of their values

Raises:

TypeError – Cannot perform operation on value

Parameters:

other (OptVariable)

bluemira.utilities.opt_variables.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

Parameters:

  • name (str)

  • value (float)

  • lower_bound (float)

  • upper_bound (float)

  • fixed (bool)

  • description (str | None)

Return type:

dataclasses.field

class bluemira.utilities.opt_variables.OptVariablesFrame

Class to model the variables for an optimisation

__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

Return type:

collections.abc.Iterator[OptVariable]

__getitem__(name: str) → OptVariable

Dictionary-like access to variables.

Parameters:

name (str) – Name of the variable to get

Returns:

The opt variable

Return type:

OptVariable

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.

Parameters:

  • name (str) – Name of the variable to adjust

  • value (float | None) – Value of the variable to set

  • lower_bound (float | None) – Value of the lower bound to set

  • upper_bound (float | None) – Value of the upper to set

  • fixed (bool) – Whether or not the variable is to be held constant

  • strict_bounds (bool) – If True, will raise errors if values are outside the bounds. If False, the bounds are dynamically adjusted to match the value.

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

Adjust multiple variables in the frame.

Parameters:

  • var_dict (VarDictT | None) – Dictionary with which to update the set, of the form {“var_name”: {“value”: v, “lower_bound”: lb, “upper_bound”: ub}, …}

  • strict_bounds (bool) – If True, will raise errors if values are outside the bounds. If False, the bounds are dynamically adjusted to match the value.

Raises:

OptVariablesError – var_dict structure not correct

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

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

Parameters:

  • name (str) – Name of the variable to fix

  • value (float | None) – Value at which to fix the variable (will default to present value)

get_normalised_values() → numpy.typing.NDArray[numpy.float64]

Get the normalised values of all free variables.

Returns:

x_norm – Array of normalised values

Return type:

np.ndarray

set_values_from_norm(x_norm)

Set values from a normalised vector.

Parameters:

x_norm (np.ndarray) – Array of normalised values

get_values_from_norm(x_norm: numpy.typing.NDArray[numpy.float64]) → list[float]

Get actual values from a normalised vector.

Parameters:

x_norm (np.ndarray) – Array of normalised values

Returns:

x_true – Array of actual values in units

Return type:

np.ndarray

Raises:

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

property names

All variable names of the variable set.

property values

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

property n_free_variables: int

Number of free variables in the set.

Return type:

int

property _opt_vars
property _fixed_vars
property _fixed_variable_indices: list

Indices of fixed variables in the set.

Return type:

list

as_dict() → dict[str, OptVarDictT]
Returns:

Dictionary Representation of the frame

Return type:

dict[str, OptVarDictT]

as_serialisable() → dict[str, OptVarSerialisedT]
Returns:

Serialised Representation of the frame

Return type:

dict[str, OptVarSerialisedT]

to_json(file: str, **kwargs)

Save the OptVariablesFrame to a json file.

Parameters:

  • path (str) – Path to save the json file to.

  • file (str)

classmethod from_json(file: pathlib.Path | str | TextIO) → OptVariablesFrame

Create an OptVariablesFrame instance from a json file.

Parameters:

file (Union[str, TextIO]) – The path to the file, or an open file handle that supports reading.

Returns:

The new instance

Return type:

OptVariablesFrame

tabulate(tablefmt: str = 'fancy_grid') → str

Tabulate OptVariablesFrame

Parameters:

tablefmt (str) – The format of the table - see https://github.com/astanin/python-tabulate#table-format

Returns:

The tabulated data

Return type:

tabulated

__str__() → str
Returns:

A pretty representation of the OptVariablesFrame inside the console

Return type:

str

__repr__() → str
Returns:

A representation of the OptVariablesFrame inside the console

Return type:

str