periodic

startorch.periodic.sequence

Contain some periodic sequence generators.

startorch.periodic.sequence.BasePeriodicSequenceGenerator

Bases: ABC

Define the base class to generate periodic sequences.

A child class has to implement the generate method.

Example usage:

>>> import torch
>>> from startorch.periodic.sequence import Repeat
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(RandUniform())
>>> generator
RepeatPeriodicSequenceGenerator(
  (generator): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
tensor([[...]])

startorch.periodic.sequence.BasePeriodicSequenceGenerator.generate abstractmethod

generate(
    seq_len: int,
    period: int,
    batch_size: int = 1,
    rng: Generator | None = None,
) -> Tensor

Generate a batch of periodic sequences.

All the sequences in the batch have the same length.

Parameters:

Name	Type	Description	Default
seq_len	int	The sequence length.	required
period	int	The period.	required
batch_size	int	The batch size.	1
rng	Generator | None	An optional random number generator.	None

Returns:

Type	Description
Tensor	A batch of sequences represented as a tensor of shape (batch_size, sequence_length, *) where * means any number of dimensions.

Example usage:

>>> import torch
>>> from startorch.periodic.sequence import Repeat
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(RandUniform())
>>> generator.generate(seq_len=12, period=4, batch_size=4)
tensor([[...]])

startorch.periodic.sequence.Repeat

Bases: BasePeriodicSequenceGenerator

Implement a class to generate periodic sequences by using a BaseSequenceGenerator object and repeating the generated sequence.

Parameters:

Name	Type	Description	Default
generator	BaseSequenceGenerator | dict	A sequence generator or its configuration.	required

Example usage:

>>> import torch
>>> from startorch.periodic.sequence import Repeat
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(RandUniform())
>>> generator
RepeatPeriodicSequenceGenerator(
  (generator): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
tensor([[...]])

startorch.periodic.sequence.RepeatPeriodicSequenceGenerator

Bases: BasePeriodicSequenceGenerator

Implement a class to generate periodic sequences by using a BaseSequenceGenerator object and repeating the generated sequence.

Parameters:

Name	Type	Description	Default
generator	BaseSequenceGenerator | dict	A sequence generator or its configuration.	required

Example usage:

>>> import torch
>>> from startorch.periodic.sequence import Repeat
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(RandUniform())
>>> generator
RepeatPeriodicSequenceGenerator(
  (generator): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
tensor([[...]])

startorch.periodic.sequence.SineWave

Bases: BasePeriodicSequenceGenerator

Implement a periodic sequence generator that generates periodic sequence by sampling values with a sine wave pattern.

The sequences are generated by using the following formula:

output = amplitude * sin(2 * pi * frequency * value + phase)

Parameters:

Name	Type	Description	Default
value	BasePeriodicSequenceGenerator | dict	A sequence generator (or its configuration) to generate the sequence values.	required
phase	BasePeriodicSequenceGenerator | dict	A sequence generator (or its configuration) to generate the phase values.	required
amplitude	BasePeriodicSequenceGenerator | dict	A sequence generator (or its configuration) to generate the amplitude values.	required

Example usage:

>>> import torch
>>> from startorch.periodic.sequence import Repeat, SineWave
>>> from startorch.sequence import RandUniform
>>> generator = SineWave(
...     value=Repeat(RandUniform(low=-1.0, high=1.0)),
...     phase=Repeat(RandUniform(low=-1.0, high=1.0)),
...     amplitude=Repeat(RandUniform(low=-1.0, high=1.0)),
... )
>>> generator
SineWavePeriodicSequenceGenerator(
  (value): RepeatPeriodicSequenceGenerator(
      (generator): RandUniformSequenceGenerator(low=-1.0, high=1.0, feature_size=(1,))
    )
  (phase): RepeatPeriodicSequenceGenerator(
      (generator): RandUniformSequenceGenerator(low=-1.0, high=1.0, feature_size=(1,))
    )
  (amplitude): RepeatPeriodicSequenceGenerator(
      (generator): RandUniformSequenceGenerator(low=-1.0, high=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
tensor([[...]])

startorch.periodic.sequence.SineWavePeriodicSequenceGenerator

Bases: BasePeriodicSequenceGenerator

Implement a periodic sequence generator that generates periodic sequence by sampling values with a sine wave pattern.

The sequences are generated by using the following formula:

output = amplitude * sin(2 * pi * frequency * value + phase)

Parameters:

Name	Type	Description	Default
value	BasePeriodicSequenceGenerator | dict	A sequence generator (or its configuration) to generate the sequence values.	required
phase	BasePeriodicSequenceGenerator | dict	A sequence generator (or its configuration) to generate the phase values.	required
amplitude	BasePeriodicSequenceGenerator | dict	A sequence generator (or its configuration) to generate the amplitude values.	required

Example usage:

>>> import torch
>>> from startorch.periodic.sequence import Repeat, SineWave
>>> from startorch.sequence import RandUniform
>>> generator = SineWave(
...     value=Repeat(RandUniform(low=-1.0, high=1.0)),
...     phase=Repeat(RandUniform(low=-1.0, high=1.0)),
...     amplitude=Repeat(RandUniform(low=-1.0, high=1.0)),
... )
>>> generator
SineWavePeriodicSequenceGenerator(
  (value): RepeatPeriodicSequenceGenerator(
      (generator): RandUniformSequenceGenerator(low=-1.0, high=1.0, feature_size=(1,))
    )
  (phase): RepeatPeriodicSequenceGenerator(
      (generator): RandUniformSequenceGenerator(low=-1.0, high=1.0, feature_size=(1,))
    )
  (amplitude): RepeatPeriodicSequenceGenerator(
      (generator): RandUniformSequenceGenerator(low=-1.0, high=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
tensor([[...]])

startorch.periodic.sequence.is_periodic_sequence_generator_config

is_periodic_sequence_generator_config(config: dict) -> bool

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

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 BasePeriodicSequenceGenerator object.

Example usage:

>>> from startorch.periodic.sequence import is_periodic_sequence_generator_config
>>> is_periodic_sequence_generator_config(
...     {
...         "_target_": "startorch.periodic.sequence.Repeat",
...         "generator": {"_target_": "startorch.sequence.RandUniform"},
...     }
... )
True

startorch.periodic.sequence.setup_periodic_sequence_generator

setup_periodic_sequence_generator(
    generator: BasePeriodicSequenceGenerator | dict,
) -> BasePeriodicSequenceGenerator

Set up a periodic sequence generator.

The sequence generator is instantiated from its configuration by using the BasePeriodicSequenceGenerator factory function.

Parameters:

Name	Type	Description	Default
generator	BasePeriodicSequenceGenerator | dict	A periodic sequence generator or its configuration.	required

Returns:

Type	Description
BasePeriodicSequenceGenerator	A periodic sequence generator.

Example usage:

>>> from startorch.periodic.sequence import setup_periodic_sequence_generator
>>> setup_periodic_sequence_generator(
...     {
...         "_target_": "startorch.periodic.sequence.Repeat",
...         "generator": {"_target_": "startorch.sequence.RandUniform"},
...     }
... )
RepeatPeriodicSequenceGenerator(
  (generator): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
)

startorch.periodic.timeseries

Contain some periodic time series generators.

startorch.periodic.timeseries.BasePeriodicTimeSeriesGenerator

Bases: ABC

Define the base class to generate periodic time series.

A child class has to implement the generate method.

Example usage:

>>> from startorch.periodic.timeseries import Repeat
>>> from startorch.timeseries import SequenceTimeSeriesGenerator
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(
...     SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
... )
>>> generator
RepeatPeriodicTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.periodic.timeseries.BasePeriodicTimeSeriesGenerator.generate abstractmethod

generate(
    seq_len: int,
    period: int,
    batch_size: int = 1,
    rng: Generator | None = None,
) -> dict[Hashable, Tensor]

Generate a batch of periodic time series.

All the time series in the batch have the same length.

Parameters:

Name	Type	Description	Default
seq_len	int	The sequence length.	required
period	int	The period.	required
batch_size	int	The batch size.	1
rng	Generator | None	An optional random number generator.	None

Returns:

Type	Description
dict[Hashable, Tensor]	A batch of periodic time series.

Example usage:

>>> from startorch.periodic.timeseries import Repeat
>>> from startorch.timeseries import SequenceTimeSeriesGenerator
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()}))
>>> generator.generate(seq_len=12, period=4, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.periodic.timeseries.Repeat

Bases: BasePeriodicTimeSeriesGenerator

Implement a class to generate periodic sequences by using a BaseTimeSeriesGenerator object and repeating the generated sequence.

Parameters:

Name	Type	Description	Default
generator	BaseTimeSeriesGenerator | dict	A sequence generator or its configuration.	required

Example usage:

>>> from startorch.periodic.timeseries import Repeat
>>> from startorch.timeseries import SequenceTimeSeriesGenerator
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(
...     SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
... )
>>> generator
RepeatPeriodicTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.periodic.timeseries.RepeatPeriodicTimeSeriesGenerator

Bases: BasePeriodicTimeSeriesGenerator

Implement a class to generate periodic sequences by using a BaseTimeSeriesGenerator object and repeating the generated sequence.

Parameters:

Name	Type	Description	Default
generator	BaseTimeSeriesGenerator | dict	A sequence generator or its configuration.	required

Example usage:

>>> from startorch.periodic.timeseries import Repeat
>>> from startorch.timeseries import SequenceTimeSeriesGenerator
>>> from startorch.sequence import RandUniform
>>> generator = Repeat(
...     SequenceTimeSeriesGenerator({"value": RandUniform(), "time": RandUniform()})
... )
>>> generator
RepeatPeriodicTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
)
>>> generator.generate(seq_len=12, period=4, batch_size=4)
{'value': tensor([[...]]), 'time': tensor([[...]])}

startorch.periodic.timeseries.is_periodic_timeseries_generator_config

is_periodic_timeseries_generator_config(
    config: dict,
) -> bool

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

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 BasePeriodicTimeSeriesGenerator object.

Example usage:

>>> from startorch.periodic.timeseries import is_periodic_timeseries_generator_config
>>> is_periodic_timeseries_generator_config(
...     {
...         "_target_": "startorch.periodic.timeseries.Repeat",
...         "generator": {
...             "_target_": "startorch.timeseries.SequenceTimeSeriesGenerator",
...             "generators": {
...                 "value": {"_target_": "startorch.sequence.RandUniform"},
...                 "time": {"_target_": "startorch.sequence.RandUniform"},
...             },
...         },
...     }
... )
True

startorch.periodic.timeseries.setup_periodic_timeseries_generator

setup_periodic_timeseries_generator(
    generator: BasePeriodicTimeSeriesGenerator | dict,
) -> BasePeriodicTimeSeriesGenerator

Set up a periodic time series generator.

The time series generator is instantiated from its configuration by using the BasePeriodicTimeSeriesGenerator factory function.

Parameters:

Name	Type	Description	Default
generator	BasePeriodicTimeSeriesGenerator | dict	A periodic time series generator or its configuration.	required

Returns:

Type	Description
BasePeriodicTimeSeriesGenerator	A periodic time series generator.

Example usage:

>>> from startorch.periodic.timeseries import setup_periodic_timeseries_generator
>>> setup_periodic_timeseries_generator(
...     {
...         "_target_": "startorch.periodic.timeseries.Repeat",
...         "generator": {
...             "_target_": "startorch.timeseries.SequenceTimeSeriesGenerator",
...             "generators": {
...                 "value": {"_target_": "startorch.sequence.RandUniform"},
...                 "time": {"_target_": "startorch.sequence.RandUniform"},
...             },
...         },
...     }
... )
RepeatPeriodicTimeSeriesGenerator(
  (generator): SequenceTimeSeriesGenerator(
      (value): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
      (time): RandUniformSequenceGenerator(low=0.0, high=1.0, feature_size=(1,))
    )
)