leaspy.models.stateful
======================

.. py:module:: leaspy.models.stateful


Classes
-------

.. autoapisummary::

   leaspy.models.stateful.StatefulModel


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

.. py:class:: StatefulModel(name, **kwargs)

   Bases: :py:obj:`leaspy.models.base.BaseModel`


   
   Stateful models have an internal :class:`~leaspy.variables.State` to handle parameters and variables.


   :Parameters:

       **name** : :obj:`str`
           The name of the model.

   :Attributes:

       **state** : :class:`~leaspy.variables.State`
           The internal state of the model, which contains the variables and their values.

       **tracked_variables** : :obj:`set` [:obj:`str`]
           Set of variable names that are tracked by the model. These variables are not necessarily part of
           the model's state but are monitored for changes or updates. This can include variables that are
           relevant for the model's operation but not directly stored in the state.













   ..
       !! processed by numpydoc !!

   .. py:attribute:: tracked_variables
      :type:  set[str]


   .. py:method:: track_variable(variable)

      
      Track a variable by its name.

      Parameters
      -------
      variable : :class:`~leaspy.variables.specs.VariableName`
          The name of the variable to track. This variable will be monitored for changes or updates.















      ..
          !! processed by numpydoc !!


   .. py:method:: track_variables(variables)

      
      Track multiple variables by their names.


      :Parameters:

          **variables** : :obj:`Iterable` [:class:`~leaspy.variables.specs.VariableName`]
              An iterable containing the names of the variables to track. Each variable will be monitored
              for changes or updates.














      ..
          !! processed by numpydoc !!


   .. py:method:: untrack_variable(variable)

      
      Untrack a variable by its name.

      Parameters
      -------
      variable : :class:`~leaspy.variables.specs.VariableName`
          The name of the variable to untrack. This variable will no longer be monitored for changes or updates.















      ..
          !! processed by numpydoc !!


   .. py:method:: untrack_variables(variables)

      
      Untrack multiple variables by their names.


      :Parameters:

          **variables** : :obj:`Iterable` [:class:`~leaspy.variables.specs.VariableName`]
              An iterable containing the names of the variables to untrack. Each variable will no longer be monitored
              for changes or updates.














      ..
          !! processed by numpydoc !!


   .. py:property:: state
      :type: leaspy.variables.state.State


      
      Get the internal state of the model.





      :Returns:

          **State** : :class:`~leaspy.variables.State`
              The internal state of the model, which contains the variables and their values.




      :Raises:

          :exc:`.LeaspyModelInputError`
              If the model's state is not initialized yet.







      ..
          !! processed by numpydoc !!


   .. py:property:: dag
      :type: leaspy.variables.dag.VariablesDAG


      
      Get the underlying DAG of the model's state.





      :Returns:

          : :class:`~leaspy.variables.dag.VariablesDAG`
              The directed acyclic graph (DAG) representing the model's variables and their relationships











      ..
          !! processed by numpydoc !!


   .. py:property:: hyperparameters_names
      :type: tuple[leaspy.variables.specs.VariableName, Ellipsis]


      
      Get the names of the model's hyperparameters.





      :Returns:

          : :obj:`tuple` [:class:`~leaspy.variables.specs.VariableName`, others...]
              A tuple containing the names of the model's hyperparameters.











      ..
          !! processed by numpydoc !!


   .. py:property:: parameters_names
      :type: tuple[leaspy.variables.specs.VariableName, Ellipsis]


      
      Get the names of the model's parameters.





      :Returns:

          : :obj:`tuple` [:class:`~leaspy.variables.specs.VariableName`, others...]
              A tuple containing the names of the model's parameters.











      ..
          !! processed by numpydoc !!


   .. py:property:: population_variables_names
      :type: tuple[leaspy.variables.specs.VariableName, Ellipsis]


      
      Get the names of the population latent variables.





      :Returns:

          : :obj:`tuple` [:class:`~leaspy.variables.specs.VariableName`, ...]
              A tuple containing the names of the population latent variables.











      ..
          !! processed by numpydoc !!


   .. py:property:: individual_variables_names
      :type: tuple[leaspy.variables.specs.VariableName, Ellipsis]


      
      Get the names of the individual latent variables.





      :Returns:

          : :obj:`tuple` [:class:`~leaspy.variables.specs.VariableName`, ...]
              A tuple containing the names of the individual latent variables.











      ..
          !! processed by numpydoc !!


   .. py:property:: parameters
      :type: leaspy.utils.typing.DictParamsTorch


      
      Dictionary of values for model parameters.





      :Returns:

          : :class:`~leaspy.utils.typing.DictParamsTorch`
              A dictionary mapping parameter names to their values (as tensors).











      ..
          !! processed by numpydoc !!


   .. py:property:: hyperparameters
      :type: leaspy.utils.typing.DictParamsTorch


      
      Dictionary of values for model hyperparameters.





      :Returns:

          : :class:`~leaspy.utils.typing.DictParamsTorch`
              A dictionary mapping hyperparameter names to their values (as tensors).











      ..
          !! processed by numpydoc !!


   .. py:method:: initialize(dataset = None)

      
      Overloads base model initialization (in particular to handle internal model State).

      <!> We do not put data variables in internal model state at this stage (done in algorithm)

      :Parameters:

          **dataset** : :class:`~leaspy.io.data.dataset.Dataset`, optional
              Input dataset from which to initialize the model.














      ..
          !! processed by numpydoc !!


   .. py:method:: load_parameters(parameters)

      
      Instantiate or update the model's parameters.

      It assumes that all model hyperparameters are defined.

      :Parameters:

          **parameters** : :class:`~leaspy.utils.typing.KwargsType`]
              Contains the model's parameters.














      ..
          !! processed by numpydoc !!


   .. py:method:: get_variables_specs()
      :abstractmethod:


      
      Return the specifications of the variables (latent variables,
      derived variables, model 'parameters') that are part of the model.





      :Returns:

          **NamedVariables** : :class:`~leaspy.variables.specs.NamedVariables`
              The specifications of the model's variables.











      ..
          !! processed by numpydoc !!


   .. py:method:: move_to_device(device)

      
      Move a model and its relevant attributes to the specified :class:`torch.device`.


      :Parameters:

          **device** : :obj:`torch.device`
              The device to which the model and its attributes should be moved.














      ..
          !! processed by numpydoc !!