leaspy.io.realizations package

Submodules

• leaspy.io.realizations.collection_realization module
  • CollectionRealization
    • CollectionRealization.clone()
    • CollectionRealization.individual
    • CollectionRealization.initialize()
    • CollectionRealization.initialize_individuals()
    • CollectionRealization.initialize_population()
    • CollectionRealization.names
    • CollectionRealization.population
    • CollectionRealization.realizations
    • CollectionRealization.realizations_dict
    • CollectionRealization.tensors
    • CollectionRealization.tensors_dict
• leaspy.io.realizations.realization module
  • AbstractRealization
    • AbstractRealization.initialize()
    • AbstractRealization.set_autograd()
    • AbstractRealization.set_tensor_realizations_element()
    • AbstractRealization.tensor
    • AbstractRealization.to_dict()
    • AbstractRealization.unset_autograd()
  • IndividualRealization
    • IndividualRealization.initialize()
    • IndividualRealization.initialize_around_mean()
    • IndividualRealization.initialize_at_mean()
    • IndividualRealization.set_autograd()
    • IndividualRealization.set_tensor_realizations_element()
    • IndividualRealization.tensor
    • IndividualRealization.to_dict()
    • IndividualRealization.unset_autograd()
  • PopulationRealization
    • PopulationRealization.initialize()
    • PopulationRealization.set_autograd()
    • PopulationRealization.set_tensor_realizations_element()
    • PopulationRealization.tensor
    • PopulationRealization.to_dict()
    • PopulationRealization.unset_autograd()

Module contents

class AbstractRealization(name: str, shape: Tuple[int, ...], *, tensor: Tensor | None = None, tensor_copy: bool = True, **kwargs)

Bases: object

Abstract class for Realization.

Parameters:

nameParamType

The name of the variable associated with the realization.

shapeTuple[int, …]

The shape of the tensor realization.

tensortorch.Tensor, optional

If not None, the tensor realization to be stored.

tensor_copybool (default True)

Whether the tensor provided is copied or not.

**kwargsdict

Additional parameters.

Attributes:

nameParamType

The name of the variable associated with the realization.

shapeTuple[int, …]

The shape of the tensor realization.

tensortorch.Tensor

The tensor realization.

Methods

initialize(model, **kwargs)	Initialize realization from a given model.
set_autograd()	Set autograd for tensor of realizations.
set_tensor_realizations_element(element, dim)	Manually change the value (in-place) of tensor_realizations at dimension dim.
to_dict()	Return a serialized dictionary of realization attributes.
unset_autograd()	Unset autograd for tensor of realizations

abstract initialize(model: AbstractModel, **kwargs: KwargsType)

Initialize realization from a given model.

Parameters:

modelAbstractModel

The model you want realizations for.

**kwargsKwargsType

Additional parameters for initialization.

Raises:

LeaspyModelInputError

if unknown variable type

set_autograd() → None

Set autograd for tensor of realizations.

TODO remove? only in legacy code

Raises:

ValueError

if inconsistent internal request

See also

torch.Tensor.requires_grad_

set_tensor_realizations_element(element: Tensor, dim: tuple[int, ...]) → None

Manually change the value (in-place) of tensor_realizations at dimension dim.

Parameters:

elementtorch.Tensor

The element to put in the tensor realization.

dimTuple[int, …]

The dimension where to put the element.

property tensor: Tensor

to_dict() → Dict[str, Any]

Return a serialized dictionary of realization attributes.

unset_autograd() → None

Unset autograd for tensor of realizations

TODO remove? only in legacy code

Raises:

ValueError

if inconsistent internal request

See also

torch.Tensor.requires_grad_

class CollectionRealization(*, population: DictRealizations | Dict[str, AbstractRealization] | None = None, individual: DictRealizations | Dict[str, AbstractRealization] | None = None)

Bases: DictRealizations

Realizations of population and individual variables, stratified per variable type.

Parameters:

populationDictRealizationsType, optional

individualDictRealizationsType, optional

Attributes:

individual

names

Return the list of variable names.

population

realizations

realizations_dict

Pooled dictionary of realizations, to (almost) provide the common DictRealizations interface.

tensors

tensors_dict

Methods

clone()	Deep-copy of the CollectionRealization instance.
initialize(model, *, n_individuals[, ...])	Initialize the CollectionRealization instance from a Model instance.
initialize_individuals(model, *, n_individuals)	Initialize the individual part of the CollectionRealization instance from a Model instance.
initialize_population(model, *[, skip_variable])	Initialize the population part of the CollectionRealization instance from a Model instance.

clone() → CollectionRealization

Deep-copy of the CollectionRealization instance.

In particular the underlying realizations are cloned and detached.

Returns:

CollectionRealization

The cloned collection of realizations.

property individual: DictRealizations

initialize(model: AbstractModel, *, n_individuals: int, skip_variable: Callable[[dict], bool] | None = None, **realization_init_kws) → None

Initialize the CollectionRealization instance from a Model instance.

Parameters:

modelAbstractModel

The model from which to initialize the collection of realizations.

n_individualsint

The number of individuals in the data.

skip_variableCallable or bool, optional

Whether some variables should be skipped or not.

**realization_init_kwsdict

Kwargs for initializing the Realizations.

initialize_individuals(model: AbstractModel, *, n_individuals: int, skip_variable: Callable[[dict], bool] | None = None, **realization_init_kws) → None

Initialize the individual part of the CollectionRealization instance from a Model instance.

Parameters:

modelAbstractModel

The model from which to initialize the collection of realizations.

n_individualsint

The number of individuals in the data.

skip_variableCallable or bool, optional

Whether some variables should be skipped or not.

**realization_init_kwsdict

Kwargs for initializing the Realizations.

initialize_population(model: AbstractModel, *, skip_variable: Callable[[dict], bool] | None = None, **realization_init_kws) → None

Initialize the population part of the CollectionRealization instance from a Model instance.

Parameters:

modelAbstractModel

The model from which to initialize the collection of realizations.

skip_variableCallable or bool, optional

Whether some variables should be skipped or not.

**realization_init_kwsdict

Kwargs for initializing the Realizations.

property names: List[str]

Return the list of variable names.

property population: DictRealizations

property realizations: List[AbstractRealization]

property realizations_dict: Dict[str, AbstractRealization]

Pooled dictionary of realizations, to (almost) provide the common DictRealizations interface.

property tensors: List[Tensor]

property tensors_dict: Dict[str, Tensor]

class DictRealizations(realizations: Dict[str, AbstractRealization] | None = None)

Bases: object

Dictionary of abstract realizations providing an easy-to-use interface.

Parameters:

realizationsDict[str, AbstractRealization], optional

The dictionary of realizations (empty if None).

Attributes:

realizations_dictDict[str, AbstractRealization]

Methods

clone()

Deep-copy of the CollectionRealization instance.

clone()

Deep-copy of the CollectionRealization instance.

In particular the underlying realizations are cloned and detached.

Returns:

CollectionRealization

The cloned collection of realizations.

property names: List[str]

Return the list of variable names.

property realizations: List[AbstractRealization]

property tensors: List[Tensor]

property tensors_dict: Dict[str, Tensor]

class IndividualRealization(name: str, shape: Tuple[int, ...], *, n_individuals: int, **kwargs)

Bases: AbstractRealization

Class for realizations of individual variables.

Parameters:

nameParamType

The name of the variable associated with the realization.

shapeTuple[int, …]

The shape of the tensor realization.

n_individualsint

The number of individuals related to this realization.

**kwargsdict

Additional parameters (including tensor and tensor_copy).

Attributes:

tensor

Methods

initialize(model, *[, init_at_mean])	Initialize the realization from a model instance.
initialize_around_mean(mean, std)	Initialize the realization around the provided mean value.
initialize_at_mean(mean)	Initialize the realization at provided mean value.
set_autograd()	Set autograd for tensor of realizations.
set_tensor_realizations_element(element, dim)	Manually change the value (in-place) of tensor_realizations at dimension dim.
to_dict()	Return a serialized dictionary of realization attributes.
unset_autograd()	Unset autograd for tensor of realizations

initialize(model: AbstractModel, *, init_at_mean: bool = False, **kwargs: KwargsType)

Initialize the realization from a model instance.

Parameters:

modelAbstractModel

The model from which to initialize the realization.

init_at_meanbool, optional

If True, the realization is initialized at the corresponding variable mean value, otherwise it the initial value is sampled around its mean value with a normal distribution.

**kwargsKwargsType

Additional parameters for initialization.

initialize_around_mean(mean: Tensor, std: Tensor) → None

Initialize the realization around the provided mean value.

The initial value is sampled according to a normal distribution with provided mean and std parameters.

Parameters:

meantorch.Tensor

Mean value around which to sample the initial value.

stdtorch.Tensor

Standard deviation for the normal distribution used to sample the initial value.

initialize_at_mean(mean: Tensor) → None

Initialize the realization at provided mean value.

Parameters:

meantorch.Tensor

The mean at which to initialize the realization.

set_autograd() → None

Set autograd for tensor of realizations.

TODO remove? only in legacy code

Raises:

ValueError

if inconsistent internal request

See also

torch.Tensor.requires_grad_

set_tensor_realizations_element(element: Tensor, dim: tuple[int, ...]) → None

Manually change the value (in-place) of tensor_realizations at dimension dim.

Parameters:

elementtorch.Tensor

The element to put in the tensor realization.

dimTuple[int, …]

The dimension where to put the element.

property tensor: Tensor

to_dict()

Return a serialized dictionary of realization attributes.

unset_autograd() → None

Unset autograd for tensor of realizations

TODO remove? only in legacy code

Raises:

ValueError

if inconsistent internal request

See also

torch.Tensor.requires_grad_

class PopulationRealization(name: str, shape: Tuple[int, ...], *, tensor: Tensor | None = None, tensor_copy: bool = True, **kwargs)

Bases: AbstractRealization

Class for realizations of population variables.

Parameters:

nameParamType

The name of the variable associated with the realization.

shapeTuple[int, …]

The shape of the tensor realization.

tensortorch.Tensor, optional

If not None, the tensor realization to be stored.

tensor_copybool (default True)

Whether the tensor provided is copied or not.

**kwargsdict

Additional parameters.

Attributes:

tensor

Methods

initialize(model, **kwargs)	Initialize the realization from a model instance.
set_autograd()	Set autograd for tensor of realizations.
set_tensor_realizations_element(element, dim)	Manually change the value (in-place) of tensor_realizations at dimension dim.
to_dict()	Return a serialized dictionary of realization attributes.
unset_autograd()	Unset autograd for tensor of realizations

initialize(model: AbstractModel, **kwargs: KwargsType) → None

Initialize the realization from a model instance.

Parameters:

modelAbstractModel

The model from which to initialize the realization.

**kwargsKwargsType

Additional parameters for initialization.

set_autograd() → None

Set autograd for tensor of realizations.

TODO remove? only in legacy code

Raises:

ValueError

if inconsistent internal request

See also

torch.Tensor.requires_grad_

set_tensor_realizations_element(element: Tensor, dim: tuple[int, ...]) → None

Manually change the value (in-place) of tensor_realizations at dimension dim.

Parameters:

elementtorch.Tensor

The element to put in the tensor realization.

dimTuple[int, …]

The dimension where to put the element.

property tensor: Tensor

to_dict() → Dict[str, Any]

Return a serialized dictionary of realization attributes.

unset_autograd() → None

Unset autograd for tensor of realizations

TODO remove? only in legacy code

Raises:

ValueError

if inconsistent internal request

See also

torch.Tensor.requires_grad_

class VariableType(value)

Bases: Enum

Possible types for variables.

INDIVIDUAL = 1

POPULATION = 2

classmethod from_string(variable_type: str)

realization_factory(realization_or_variable_type: AbstractRealization | VariableType | str, **kws) → AbstractRealization

Factory for Realizations.

Parameters:

realization_or_variable_typeAbstractRealization or VariableType or str

If an instance of a subclass of AbstractRealization, returns the instance (no copy). If a VariableType variant (or a valid string keyword for this variant), then returns a new instance of the appropriate class (with optional parameters kws).

**kws

Optional parameters for initializing the requested Realization (not used if input is a subclass of AbstractRealization).

Returns:

AbstractRealization

The desired realization.

Raises:

LeaspyInputError:

If the variable type provided is not supported.