random

startorch.random

Contain functions to generate tensors filled with random values.

startorch.random.asinh_uniform

asinh_uniform(
    low: Tensor,
    high: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a uniform distribution in the inverse hyperbolic sine space.

Parameters:

Name	Type	Description	Default
low	Tensor	The minimum values (inclusive). It must be a float tensor of shape (d0, d1, ..., dn).	required
high	Tensor	The maximum values (exclusive). It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a uniform distribution in the inverse hyperbolic sine space where the minimum and maximum values are given as input.

Raises:

Type	Description
ValueError	if the low and high parameters are not valid.

Example usage:

>>> from startorch.random import asinh_uniform
>>> asinh_uniform(
...     low=torch.tensor([-10.0, 0.0, 1.0]),
...     high=torch.tensor([1.0, 10.0, 100.0]),
... )
tensor([...])

startorch.random.cauchy

cauchy(
    loc: Tensor,
    scale: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a Cauchy distribution.

Unlike rand_cauchy, this function allows to sample values from different Cauchy distributions at the same time. The shape of the loc and scale tensors are used to infer the output size.

Parameters:

Name	Type	Description	Default
loc	Tensor	The location/median of the Cauchy distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
scale	Tensor	The standard deviation of the Cauchy distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a Cauchy distribution.

Raises:

Type	Description
ValueError	if the loc and scale parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import cauchy
>>> cauchy(loc=torch.tensor([-1.0, 0.0, 1.0]), scale=torch.tensor([1.0, 3.0, 5.0]))
tensor([...])

startorch.random.exponential

exponential(
    rate: Tensor, generator: Generator | None = None
) -> Tensor

Create a tensor filled with values sampled from an Exponential distribution.

Unlike rand_exponential, this function allows to sample values from different Exponential distributions at the same time. The shape of the rate tensor is used to infer the output size.

Parameters:

Name	Type	Description	Default
rate	Tensor	The rates of the Exponential distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from an Exponential distribution.

Raises:

Type	Description
ValueError	if the rate parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import exponential
>>> exponential(torch.tensor([1.0, 3.0, 5.0]))
tensor([...])

startorch.random.half_cauchy

half_cauchy(
    scale: Tensor, generator: Generator | None = None
) -> Tensor

Create a tensor filled with values sampled from a half-Cauchy distribution.

Unlike rand_half_cauchy, this function allows to sample values from different half-Cauchy distributions at the same time. The shape of the scale tensor is used to infer the output size.

Parameters:

Name	Type	Description	Default
scale	Tensor	The scale of the half-Cauchy distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a half-Cauchy distribution.

Raises:

Type	Description
ValueError	if the scale parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import half_cauchy
>>> half_cauchy(torch.tensor([1.0, 3.0, 5.0]))
tensor([...])

startorch.random.half_normal

half_normal(
    std: Tensor, generator: Generator | None = None
) -> Tensor

Create a tensor filled with values sampled from a half-Normal distribution.

Unlike rand_half_normal, this function allows to sample values from different half-Normal distributions at the same time. The shape of the std tensor is used to infer the output size.

Parameters:

Name	Type	Description	Default
std	Tensor	The standard deviation of the half-Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	Specifies an optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a half-Normal distribution.

Raises:

Type	Description
ValueError	if the std parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import half_normal
>>> half_normal(torch.tensor([1.0, 3.0, 5.0]))
tensor([...])

startorch.random.log_normal

log_normal(
    mean: Tensor,
    std: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a log-Normal distribution.

Unlike rand_log_normal, this function allows to sample values from different log-Normal distributions at the same time. The shape of the mean and std tensors are used to infer the output size.

Parameters:

Name	Type	Description	Default
mean	Tensor	The mean of the log-Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
std	Tensor	The standard deviation of the log-Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a log-Normal distribution.

Raises:

Type	Description
ValueError	if the mean and std parametera are not valid.

Example usage:

>>> import torch
>>> from startorch.random import log_normal
>>> log_normal(torch.tensor([-1.0, 0.0, 1.0]), torch.tensor([1.0, 3.0, 5.0]))
tensor([...])

startorch.random.log_uniform

log_uniform(
    low: Tensor,
    high: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a uniform distribution in the log space.

Parameters:

Name	Type	Description	Default
low	Tensor	The minimum values (inclusive). It must be a float tensor of shape (d0, d1, ..., dn).	required
high	Tensor	The maximum values (exclusive). It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a uniform distribution in the log space where the minimum and maximum values are given as input.

Raises:

Type	Description
ValueError	if the low and high parameters are not valid.

Example usage:

>>> from startorch.random import log_uniform
>>> log_uniform(low=torch.tensor([0.01, 0.1, 1.0]), high=torch.tensor([1.0, 10.0, 100.0]))
tensor([...])

startorch.random.normal

normal(
    mean: Tensor,
    std: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a Normal distribution.

Parameters:

Name	Type	Description	Default
mean	Tensor	The mean. It must be a float tensor of shape (d0, d1, ..., dn).	required
std	Tensor	The standard deviation. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a Normal distribution.

Raises:

Type	Description
ValueError	if the mean and std parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import normal
>>> normal(mean=torch.tensor([-1.0, 0.0, 1.0]), std=torch.tensor([1.0, 3.0, 5.0]))
tensor([...])

startorch.random.rand_asinh_uniform

rand_asinh_uniform(
    size: list[int] | tuple[int, ...],
    low: float,
    high: float,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a uniform distribution in the inverse hyperbolic sine space.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
low	float	The minimum value (inclusive). This value needs to be positive.	required
high	float	The maximum value (exclusive).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a uniform distribution in the inverse hyperbolic sine space.

Raises:

Type	Description
ValueError	if the low and high parameters are not valid.

Example usage:

>>> from startorch.random import rand_asinh_uniform
>>> rand_asinh_uniform((2, 3), low=-1000.0, high=1000.0)
tensor([[...]])

startorch.random.rand_cauchy

rand_cauchy(
    size: list[int] | tuple[int, ...],
    loc: float = 0.0,
    scale: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a sequence of continuous variables sampled from a Cauchy distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
loc	float	The location/median of the Cauchy distribution.	0.0
scale	float	The scale of the Cauchy distribution. This value has to be greater than 0.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a Cauchy distribution.

Raises:

Type	Description
ValueError	if the scale parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_cauchy
>>> rand_cauchy((2, 3), loc=1.0, scale=2.0)
tensor([[...]])

startorch.random.rand_exponential

rand_exponential(
    size: list[int] | tuple[int, ...],
    rate: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from an Exponential distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
rate	float	The rate of the Exponential distribution.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from an Exponential distribution.

Raises:

Type	Description
ValueError	if the rate parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_exponential
>>> rand_exponential((2, 3), rate=1.0)
tensor([[...]])

startorch.random.rand_half_cauchy

rand_half_cauchy(
    size: list[int] | tuple[int, ...],
    scale: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a half-Cauchy distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
scale	float	The scale of the half-Cauchy distribution. This value has to be greater than 0.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a half-Cauchy distribution.

Raises:

Type	Description
ValueError	if the scale parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_half_cauchy
>>> rand_half_cauchy((2, 3), scale=1.0)
tensor([[...]])

startorch.random.rand_half_normal

rand_half_normal(
    size: list[int] | tuple[int, ...],
    std: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a half-Normal distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
std	float	The standard deviation of the half-Normal distribution.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a half-Normal distribution.

Raises:

Type	Description
ValueError	if the std parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_half_normal
>>> rand_half_normal((2, 3), std=1.0)
tensor([[...]])

startorch.random.rand_log_normal

rand_log_normal(
    size: list[int] | tuple[int, ...],
    mean: float = 0.0,
    std: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a log-Normal distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
mean	float	The mean of the underlying Normal distribution.	0.0
std	float	The standard deviation of the underlying Normal distribution.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a log-Normal distribution.

Raises:

Type	Description
ValueError	if the mean and std parametera are not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_log_normal
>>> rand_log_normal((2, 3), mean=1.0, std=2.0)
tensor([[...]])

startorch.random.rand_log_uniform

rand_log_uniform(
    size: list[int] | tuple[int, ...],
    low: float,
    high: float,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a uniform distribution in the log space.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
low	float	The minimum value (inclusive). This value needs to be positive.	required
high	float	The maximum value (exclusive).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a uniform distribution in the log space.

Raises:

Type	Description
ValueError	if the low and high parameters are not valid.

Example usage:

>>> from startorch.random import rand_log_uniform
>>> rand_log_uniform((2, 3), low=0.1, high=1000.0)
tensor([[...]])

startorch.random.rand_normal

rand_normal(
    size: list[int] | tuple[int, ...],
    mean: float = 0.0,
    std: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a Normal distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
mean	float	The mean of the Normal distribution.	0.0
std	float	The standard deviation of the Normal distribution.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a Normal distribution.

Raises:

Type	Description
ValueError	if the std parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_normal
>>> rand_normal((2, 3), mean=1.0, std=2.0)
tensor([[...]])

startorch.random.rand_poisson

rand_poisson(
    size: list[int] | tuple[int, ...],
    rate: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a Poisson distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
rate	float	The rate of the Poisson distribution. This value has to be greater than 0.	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	torch.Tensor of type float: A tensor filled with values sampled from a Poisson distribution.

Raises:

Type	Description
ValueError	if the rate parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_poisson
>>> rand_poisson(size=(2, 3), rate=2.0)
tensor([...])

startorch.random.rand_trunc_cauchy

rand_trunc_cauchy(
    size: list[int] | tuple[int, ...],
    loc: float = 0.0,
    scale: float = 1.0,
    min_value: float = -2.0,
    max_value: float = 2.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated Cauchy distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
loc	float	The location of the Cauchy distribution.	0.0
scale	float	The scale of the Cauchy distribution.	1.0
min_value	float	The minimum value.	-2.0
max_value	float	The maximum value.	2.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a truncated Cauchy distribution

Raises:

Type	Description
ValueError	if the max_value and min_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_trunc_cauchy
>>> rand_trunc_cauchy((2, 3), loc=1.0, scale=2.0, min_value=-3.0, max_value=3.0)
tensor([[...]])

startorch.random.rand_trunc_exponential

rand_trunc_exponential(
    size: list[int] | tuple[int, ...],
    rate: float = 1.0,
    max_value: float = 5.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated Exponential distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
rate	float	The rate of the Exponential distribution.	1.0
max_value	float	The maximum value.	5.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a truncated Exponential distribution

Raises:

Type	Description
ValueError	if the max_value parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_trunc_exponential
>>> rand_trunc_exponential((2, 3), rate=1.0, max_value=3.0)
tensor([[...]])

startorch.random.rand_trunc_half_cauchy

rand_trunc_half_cauchy(
    size: list[int] | tuple[int, ...],
    scale: float = 1.0,
    max_value: float = 4.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated half- Cauchy distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
scale	float	The scale of the half-Cauchy distribution.	1.0
max_value	float	The maximum value.	4.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a truncated half-Cauchy distribution.

Raises:

Type	Description
ValueError	if the max_value parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_trunc_half_cauchy
>>> rand_trunc_half_cauchy((2, 3), scale=1.0, max_value=3.0)
tensor([[...]])

startorch.random.rand_trunc_half_normal

rand_trunc_half_normal(
    size: list[int] | tuple[int, ...],
    std: float = 1.0,
    max_value: float = 5.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated half- Normal distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
std	float	The standard deviation of the half-Normal distribution.	1.0
max_value	float	The maximum value.	5.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a truncated half-Normal distribution.

Raises:

Type	Description
ValueError	if the max_value parameter is not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_trunc_half_normal
>>> rand_trunc_half_normal((2, 3), std=1.0, max_value=3.0)
tensor([[...]])

startorch.random.rand_trunc_log_normal

rand_trunc_log_normal(
    size: list[int] | tuple[int, ...],
    mean: float = 0.0,
    std: float = 1.0,
    min_value: float = 0.0,
    max_value: float = 5.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated log- Normal distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
mean	float	The mean of the underlying Normal distribution.	0.0
std	float	The standard deviation of the underlying Normal distribution.	1.0
min_value	float	The minimum value.	0.0
max_value	float	The maximum value.	5.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a truncated log-Normal distribution.

Raises:

Type	Description
ValueError	if the min_value and max_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_trunc_log_normal
>>> rand_trunc_log_normal((2, 3), mean=0.0, std=1.0, min_value=1.0, max_value=4.0)
tensor([[...]])

startorch.random.rand_trunc_normal

rand_trunc_normal(
    size: list[int] | tuple[int, ...],
    mean: float = 0.0,
    std: float = 1.0,
    min_value: float = -3.0,
    max_value: float = 3.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated Normal distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
mean	float	The mean of the Normal distribution.	0.0
std	float	The standard deviation of the Normal distribution.	1.0
min_value	float	The minimum value.	-3.0
max_value	float	The maximum value.	3.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a truncated Normal distribution.

Raises:

Type	Description
ValueError	if the min_value and max_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_trunc_normal
>>> rand_trunc_normal((2, 3), mean=1.0, std=2.0, min_value=-5.0, max_value=5.0)
tensor([[...]])

startorch.random.rand_uniform

rand_uniform(
    size: list[int] | tuple[int, ...],
    low: float = 0.0,
    high: float = 1.0,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a uniform distribution.

Parameters:

Name	Type	Description	Default
size	list[int] | tuple[int, ...]	The tensor shape.	required
low	float	The minimum value (inclusive).	0.0
high	float	The maximum value (exclusive).	1.0
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor filled with values sampled from a uniform distribution.

Raises:

Type	Description
ValueError	if the low and high parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import rand_uniform
>>> rand_uniform((2, 3), low=-1.0, high=2.0)
tensor([[...]])

startorch.random.trunc_cauchy

trunc_cauchy(
    loc: Tensor,
    scale: Tensor,
    min_value: Tensor,
    max_value: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated Cauchy distribution.

Parameters:

Name	Type	Description	Default
loc	Tensor	The location/median of the Cauchy distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
scale	Tensor	The scale of the Cauchy distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
min_value	Tensor	The minimum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
max_value	Tensor	The maximum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a truncated Cauchy distribution

Raises:

Type	Description
ValueError	if the loc, scale, max_value and min_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import trunc_cauchy
>>> trunc_cauchy(
...     loc=torch.tensor([1.0, 0.0, -1.0]),
...     scale=torch.tensor([1.0, 3.0, 5.0]),
...     min_value=torch.tensor([-5.0, -10.0, -15.0]),
...     max_value=torch.tensor([5.0, 10.0, 15.0]),
... )
tensor([...])

startorch.random.trunc_exponential

trunc_exponential(
    rate: Tensor,
    max_value: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated Exponential distribution.

Parameters:

Name	Type	Description	Default
rate	Tensor	The rate of the Exponential distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
max_value	Tensor	The maximum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a truncated Exponential distribution.

Raises:

Type	Description
ValueError	if the rate and max_value parameter are not valid.

Example usage:

>>> import torch
>>> from startorch.random import trunc_exponential
>>> trunc_exponential(
...     rate=torch.tensor([1.0, 3.0, 5.0]),
...     max_value=torch.tensor([5.0, 10.0, 15.0]),
... )
tensor([...])

startorch.random.trunc_half_cauchy

trunc_half_cauchy(
    scale: Tensor,
    max_value: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated half- Cauchy distribution.

Parameters:

Name	Type	Description	Default
scale	Tensor	The scale of the half-Cauchy distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
max_value	Tensor	The maximum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a truncated Cauchy distribution.

Raises:

Type	Description
ValueError	if the scale and max_value parameter are not valid.

Example usage:

>>> import torch
>>> from startorch.random import trunc_half_cauchy
>>> trunc_half_cauchy(
...     scale=torch.tensor([1.0, 3.0, 5.0]),
...     max_value=torch.tensor([5.0, 10.0, 15.0]),
... )
tensor([...])

startorch.random.trunc_half_normal

trunc_half_normal(
    std: Tensor,
    max_value: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated half- Normal distribution.

Parameters:

Name	Type	Description	Default
std	Tensor	The standard deviation of the half-Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
max_value	Tensor	The maximum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a truncated half-Normal distribution.

Raises:

Type	Description
ValueError	if the std and max_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import trunc_half_normal
>>> trunc_half_normal(
...     std=torch.tensor([1.0, 3.0, 5.0]), max_value=torch.tensor([5.0, 10.0, 15.0])
... )
tensor([...])

startorch.random.trunc_log_normal

trunc_log_normal(
    mean: Tensor,
    std: Tensor,
    min_value: Tensor,
    max_value: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated log- Normal distribution.

Parameters:

Name	Type	Description	Default
mean	Tensor	The mean of the underlying Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
std	Tensor	The standard deviation of the underlying Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
min_value	Tensor	The minimum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
max_value	Tensor	The maximum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a truncated log-Normal distribution.

Raises:

Type	Description
ValueError	if the mean, std, min_value and max_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import trunc_log_normal
>>> trunc_log_normal(
...     mean=torch.tensor([-1.0, 0.0, 1.0]),
...     std=torch.tensor([1.0, 3.0, 5.0]),
...     min_value=torch.tensor([0.0, 1.0, 2.0]),
...     max_value=torch.tensor([5.0, 10.0, 15.0]),
... )
tensor([...])

startorch.random.trunc_normal

trunc_normal(
    mean: Tensor,
    std: Tensor,
    min_value: Tensor,
    max_value: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a truncated Normal distribution.

Parameters:

Name	Type	Description	Default
mean	Tensor	The mean of the Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
std	Tensor	The standard deviation of the Normal distribution. It must be a float tensor of shape (d0, d1, ..., dn).	required
min_value	Tensor	The minimum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
max_value	Tensor	The maximum value. It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a truncated Normal distribution.

Raises:

Type	Description
ValueError	if the min_value and max_value parameters are not valid.

Example usage:

>>> import torch
>>> from startorch.random import trunc_normal
>>> trunc_normal(
...     mean=torch.tensor([1.0, 0.0, -1.0]),
...     std=torch.tensor([1.0, 3.0, 5.0]),
...     min_value=torch.tensor([-5.0, -10.0, -15.0]),
...     max_value=torch.tensor([5.0, 10.0, 15.0]),
... )
tensor([...])

startorch.random.uniform

uniform(
    low: Tensor,
    high: Tensor,
    generator: Generator | None = None,
) -> Tensor

Create a tensor filled with values sampled from a uniform distribution.

Unlike rand_uniform, this function allows to sample values from different uniform distributions at the same time. The shape of the low and high tensors are used to infer the output size.

Parameters:

Name	Type	Description	Default
low	Tensor	The minimum values (inclusive). It must be a float tensor of shape (d0, d1, ..., dn).	required
high	Tensor	The maximum values (exclusive). It must be a float tensor of shape (d0, d1, ..., dn).	required
generator	Generator | None	An optional random generator.	None

Returns:

Type	Description
Tensor	A tensor of shape (d0, d1, ..., dn) filled with values sampled from a uniform distribution where the minimum and maximum values are given as input.

Raises:

Type	Description
ValueError	if the input tensor shapes do not match or if at least one value in low tensor is higher than its associated high value in high

Example usage:

>>> import torch
>>> from startorch.random import uniform
>>> uniform(low=torch.tensor([-1.0, 0.0, 1.0]), high=torch.tensor([1.0, 3.0, 5.0]))
tensor([...])