transition

startorch.transition

Contain transition matrix generators.

startorch.transition.BaseTransitionGenerator

Bases: ABC

Define the base class to generate a transition matrix.

A child class has to implement the generate method.

Example usage:

>>> import torch
>>> from startorch.transition import Diagonal
>>> generator = Diagonal()
>>> generator
DiagonalTransitionGenerator()
>>> generator.generate(n=6)
tensor([[1., 0., 0., 0., 0., 0.],
        [0., 1., 0., 0., 0., 0.],
        [0., 0., 1., 0., 0., 0.],
        [0., 0., 0., 1., 0., 0.],
        [0., 0., 0., 0., 1., 0.],
        [0., 0., 0., 0., 0., 1.]])

startorch.transition.BaseTransitionGenerator.generate abstractmethod

generate(n: int, rng: Generator | None = None) -> Tensor

Return a transition matrix.

Parameters:

Name	Type	Description	Default
n	int	The size of the transition matrix.	required
rng	Generator | None	An optional random number generator.	None

Returns:

Type	Description
Tensor	The generated transition matrix of shape (n, n) and data type float.

Example usage:

>>> import torch
>>> from startorch.transition import Diagonal
>>> generator = Diagonal()
>>> generator.generate(n=6)
tensor([[1., 0., 0., 0., 0., 0.],
        [0., 1., 0., 0., 0., 0.],
        [0., 0., 1., 0., 0., 0.],
        [0., 0., 0., 1., 0., 0.],
        [0., 0., 0., 0., 1., 0.],
        [0., 0., 0., 0., 0., 1.]])

startorch.transition.Diagonal

Bases: BaseTransitionGenerator

Implement a simple diagonal transition matrix generator.

Example usage:

>>> import torch
>>> from startorch.transition import Diagonal
>>> generator = Diagonal()
>>> generator
DiagonalTransitionGenerator()
>>> generator.generate(n=6)
tensor([[1., 0., 0., 0., 0., 0.],
        [0., 1., 0., 0., 0., 0.],
        [0., 0., 1., 0., 0., 0.],
        [0., 0., 0., 1., 0., 0.],
        [0., 0., 0., 0., 1., 0.],
        [0., 0., 0., 0., 0., 1.]])

startorch.transition.DiagonalTransitionGenerator

Bases: BaseTransitionGenerator

Implement a simple diagonal transition matrix generator.

Example usage:

>>> import torch
>>> from startorch.transition import Diagonal
>>> generator = Diagonal()
>>> generator
DiagonalTransitionGenerator()
>>> generator.generate(n=6)
tensor([[1., 0., 0., 0., 0., 0.],
        [0., 1., 0., 0., 0., 0.],
        [0., 0., 1., 0., 0., 0.],
        [0., 0., 0., 1., 0., 0.],
        [0., 0., 0., 0., 1., 0.],
        [0., 0., 0., 0., 0., 1.]])

startorch.transition.Mask

Bases: BaseTransitionGenerator

Implement a transition matrix generator that uses a tensor generator.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	The transition generator or its configuration.	required
num_mask	int	The number of values to mask on each row of the transition matrix.	required

Example usage:

>>> import torch
>>> from startorch.transition import MaskTransitionGenerator, TensorTransitionGenerator
>>> from startorch.tensor import Full
>>> generator = MaskTransitionGenerator(
...     generator=TensorTransitionGenerator(Full(1.0)), num_mask=4
... )
>>> generator
MaskTransitionGenerator(
  (generator): TensorTransitionGenerator(
      (generator): FullTensorGenerator(value=1.0, dtype=None)
    )
  (num_mask): 4
)
>>> generator.generate(n=6)
tensor([[...]])

startorch.transition.MaskTransitionGenerator

Bases: BaseTransitionGenerator

Implement a transition matrix generator that uses a tensor generator.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	The transition generator or its configuration.	required
num_mask	int	The number of values to mask on each row of the transition matrix.	required

Example usage:

>>> import torch
>>> from startorch.transition import MaskTransitionGenerator, TensorTransitionGenerator
>>> from startorch.tensor import Full
>>> generator = MaskTransitionGenerator(
...     generator=TensorTransitionGenerator(Full(1.0)), num_mask=4
... )
>>> generator
MaskTransitionGenerator(
  (generator): TensorTransitionGenerator(
      (generator): FullTensorGenerator(value=1.0, dtype=None)
    )
  (num_mask): 4
)
>>> generator.generate(n=6)
tensor([[...]])

startorch.transition.Normalize

Bases: BaseTransitionGenerator

Implement a transition matrix generator that normalizes a transition matrix.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	The transition generator or its configuration.	required
p	float	The exponent value in the norm formulation.	2.0

Example usage:

>>> import torch
>>> from startorch.transition import Normalize, TensorTransitionGenerator
>>> from startorch.tensor import Full
>>> generator = Normalize(generator=TensorTransitionGenerator(Full(1.0)))
>>> generator
NormalizeTransitionGenerator(
  (generator): TensorTransitionGenerator(
      (generator): FullTensorGenerator(value=1.0, dtype=None)
    )
  (p): 2.0
)
>>> generator.generate(n=4)
tensor([[0.5000, 0.5000, 0.5000, 0.5000],
        [0.5000, 0.5000, 0.5000, 0.5000],
        [0.5000, 0.5000, 0.5000, 0.5000],
        [0.5000, 0.5000, 0.5000, 0.5000]])

startorch.transition.NormalizeTransitionGenerator

Bases: BaseTransitionGenerator

Implement a transition matrix generator that normalizes a transition matrix.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	The transition generator or its configuration.	required
p	float	The exponent value in the norm formulation.	2.0

Example usage:

>>> import torch
>>> from startorch.transition import Normalize, TensorTransitionGenerator
>>> from startorch.tensor import Full
>>> generator = Normalize(generator=TensorTransitionGenerator(Full(1.0)))
>>> generator
NormalizeTransitionGenerator(
  (generator): TensorTransitionGenerator(
      (generator): FullTensorGenerator(value=1.0, dtype=None)
    )
  (p): 2.0
)
>>> generator.generate(n=4)
tensor([[0.5000, 0.5000, 0.5000, 0.5000],
        [0.5000, 0.5000, 0.5000, 0.5000],
        [0.5000, 0.5000, 0.5000, 0.5000],
        [0.5000, 0.5000, 0.5000, 0.5000]])

startorch.transition.PermuteDiagonal

Bases: BaseTransitionGenerator

Implement a simple diagonal transition matrix generator.

Example usage:

>>> import torch
>>> from startorch.transition import PermuteDiagonal
>>> generator = PermuteDiagonal()
>>> generator
PermuteDiagonalTransitionGenerator()
>>> generator.generate(n=6)
tensor([...]])

startorch.transition.PermuteDiagonalTransitionGenerator

Bases: BaseTransitionGenerator

Implement a simple diagonal transition matrix generator.

Example usage:

>>> import torch
>>> from startorch.transition import PermuteDiagonal
>>> generator = PermuteDiagonal()
>>> generator
PermuteDiagonalTransitionGenerator()
>>> generator.generate(n=6)
tensor([...]])

startorch.transition.TensorTransitionGenerator

Bases: BaseTransitionGenerator

Implement a transition matrix generator that uses a tensor generator.

Parameters:

Name	Type	Description	Default
generator	BaseTensorGenerator | dict	The tensor generator or its configuration.	required

Example usage:

>>> import torch
>>> from startorch.transition import TensorTransitionGenerator
>>> from startorch.tensor import RandUniform
>>> generator = TensorTransitionGenerator(generator=RandUniform())
>>> generator
TensorTransitionGenerator(
  (generator): RandUniformTensorGenerator(low=0.0, high=1.0)
)
>>> generator.generate(n=6)
tensor([[...]])

startorch.transition.Transform

Bases: BaseTransitionGenerator

Implement a transition matrix generator that transform a transition matrix.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	The transition generator or its configuration.	required
transformer	BaseTensorTransformer | dict	The tensor transformer or its configuration.	required

Example usage:

>>> import torch
>>> from startorch.transition import Transform, Diagonal
>>> from startorch.tensor.transformer import Clamp
>>> generator = Transform(generator=Diagonal(), transformer=Clamp(min=0.0, max=0.5))
>>> generator
TransformTransitionGenerator(
  (generator): DiagonalTransitionGenerator()
  (transformer): ClampTensorTransformer(min=0.0, max=0.5)
)
>>> generator.generate(n=4)
tensor([[0.5000, 0.0000, 0.0000, 0.0000],
        [0.0000, 0.5000, 0.0000, 0.0000],
        [0.0000, 0.0000, 0.5000, 0.0000],
        [0.0000, 0.0000, 0.0000, 0.5000]])

startorch.transition.TransformTransitionGenerator

Bases: BaseTransitionGenerator

Implement a transition matrix generator that transform a transition matrix.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	The transition generator or its configuration.	required
transformer	BaseTensorTransformer | dict	The tensor transformer or its configuration.	required

Example usage:

>>> import torch
>>> from startorch.transition import Transform, Diagonal
>>> from startorch.tensor.transformer import Clamp
>>> generator = Transform(generator=Diagonal(), transformer=Clamp(min=0.0, max=0.5))
>>> generator
TransformTransitionGenerator(
  (generator): DiagonalTransitionGenerator()
  (transformer): ClampTensorTransformer(min=0.0, max=0.5)
)
>>> generator.generate(n=4)
tensor([[0.5000, 0.0000, 0.0000, 0.0000],
        [0.0000, 0.5000, 0.0000, 0.0000],
        [0.0000, 0.0000, 0.5000, 0.0000],
        [0.0000, 0.0000, 0.0000, 0.5000]])

startorch.transition.is_transition_generator_config

is_transition_generator_config(config: dict) -> bool

Indicate if the input configuration is a configuration for a BaseTransitionGenerator.

This function only checks if the value of the key _target_ is valid. It does not check the other values. If _target_ indicates a function, the returned type hint is used to check the class.

Parameters:

Name	Type	Description	Default
config	dict	The configuration to check.	required

Returns:

Type	Description
bool	True if the input configuration is a configuration for a BaseTransitionGenerator object.

Example usage:

>>> from startorch.transition import is_transition_generator_config
>>> is_transition_generator_config({"_target_": "startorch.transition.Diagonal"})
True

startorch.transition.setup_transition_generator

setup_transition_generator(
    generator: BaseTransitionGenerator | dict,
) -> BaseTransitionGenerator

Set up a transition matrix generator.

The transition generator is instantiated from its configuration by using the BaseTransitionGenerator factory function.

Parameters:

Name	Type	Description	Default
generator	BaseTransitionGenerator | dict	A transition matrix generator or its configuration.	required

Returns:

Type	Description
BaseTransitionGenerator	A transition matrix generator.

Example usage:

>>> from startorch.transition import setup_transition_generator
>>> setup_transition_generator({"_target_": "startorch.transition.Diagonal"})
DiagonalTransitionGenerator()