SSD package

ssd.base module

Base classes

Base abstract classes for the distributions

class ssd.base.BaseDistribution

Bases: object

A base class for probability density functions.

grad(x: float, dx: float = 1e-09) → float

Compute the derivative of the probability density function at a given point.

Parameters:

• x (float) – The point at which to evaluate the derivative

• dx (float, optional) – The step size (default is 1e-9)

Returns:

The value of the derivative at the given point

Return type:

float

integrate(a: float = -inf, b: float = inf, moment: float = 0.0, power: float = 1.0) → Tuple[float, float]

Integrate the probability density function from a to b.

Parameters:

• a (float, optional) – The lower bound of the integration (default is -inf)

• b (float, optional) – The upper bound of the integration (default is inf)

• moment (float, optional) – The moment to compute (default is 0)

• power (float, optional) – The power to raise the integrand to (default is 1)

Returns:

The value of the integral and the error

Return type:

Tuple[float, float]

property max

property min

ssd.distributions module

Probability Density Functions

A collection of probability density functions

class ssd.distributions.EmpiricalDistribution(bw_method: str | float | Callable | None = None, weights: Iterable[float] | None = None)

Bases: BaseDistribution

Estimate an empirical distribution using a Gaussian KDE.

Parameters:

• bw_method (str, float, or callable, optional) – The method used to calculate the estimator bandwidth. This can be ‘scott’, ‘silverman’, a scalar constant or a callable. If a scalar, this will be used directly as kde.factor. If a callable, it should take a gaussian_kde instance as only parameter and return a scalar. If None (default), ‘scott’ is used. See scipy.stats.gaussian_kde for more details.

• weights (array_like, optional) – The weights for each value in the empirical distribution. This must be the same shape as the input data. See scipy.stats.gaussian_kde for more details.

fit(data: Iterable[float]) → EmpiricalDistribution

Parameters:

data (array_like) – The data to fit

Returns:

The fitted empirical distribution

Return type:

EmpiricalDistribution

property max

property min

class ssd.distributions.HistogramDistribution(bins: int | Iterable[float] = 100)

Bases: BaseDistribution

Use a histogram to estimate a probability density function.

Parameters:

bins (Union[int, Iterable[float]], optional) – The number of bins to use in the histogram (default is 100). If an iterable is provided, it will be used as the bin edges.

fit(data: Iterable[float]) → HistogramDistribution

Parameters:

data (array_like) – The data to fit

Returns:

The fitted histogram distribution

Return type:

HistogramDistribution

grad(x: float) → float

Compute the derivative of the probability density function at a given point.

Parameters:

x (float) – The point at which to compute the derivative

Returns:

The value of the derivative at the given point

Return type:

float

integrate(a: float = -inf, b: float = inf, moment: float = 1) → Tuple[float, float]

Integrate the probability density function from a to b.

Parameters:

• a (float, optional) – The lower bound of the integration (default is -inf)

• b (float, optional) – The upper bound of the integration (default is inf)

• moment (float, optional) – The moment to compute (default is 0)

Returns:

The value of the integral and the error

Return type:

Tuple[float, float]

class ssd.distributions.InterpolateDistribution(bins: int | Iterable[float] = 100)

Bases: BaseDistribution

Use a histogram distribution with interpolated values to estimate a probability density function.

Parameters:

bins (Union[int, Iterabl[float]], optional) – The number of bins to use in the histogram (default is 100). If an iterable is provided, it will be used as the bin edges.

fit(data: Iterable[float], n: int = 1, s: float = 0.01, force_origin: bool = False, epsilon: float = 1e-09) → InterpolateDistribution

Parameters:

• data (array_like) – The data to fit

• n (int, optional) – The degree of the interpolating polynomial (default is 1)

• s (float, optional) – The smoothing factor (default is 0.01)

• force_origin (bool, optional) – Force the interpolating polynomial to pass through the origin (default is False)

• epsilon (float, optional) – Small number to avoid division by zero (default is 1.e-9)

Returns:

The fitted histogram distribution

Return type:

HistogramDistribution

class ssd.distributions.InverseMarchenkoPastur(L: float, sigma: float = 1.0)

Bases: MarchenkoPastur

An inverse Marchenko-Pastur probability density function.

The Marchenko-Pastur (MP) distribution is a probability density function that describes the asymptotic distribution of the singular values of a large rectangular random matrix with Gaussian entries (i.e. the eigenvalues of the associated covariance matrix). Given a matrix \(X\) of size \(n \times p\), where \(n \to \infty\) and \(p \to \infty\), such that \(\lambda = \frac{p}{n} \in (0, 1)\), the MP distribution is defined as:

\[\mu(x) = \frac{1}{2 \pi \sigma^2} \frac{\sqrt{(\lambda_+ - x)(x - \lambda_-)}}{\lambda x} \mathbb{1}_{[x_-, x_+]}(x)\]

where

\[\lambda_+ = \sigma^2 (1 + \sqrt{\lambda})^2\]

and

\[\lambda_- = \sigma^2 (1 - \sqrt{\lambda})^2\]

are the upper and lower bounds of the function, respectively, and \(\mathbb{1}_{[x_-, x_+]}(x)\) is the indicator function of the interval \([x_-, x_+]\).

Parameters:

• L (float) – The ratio \(\lambda = \frac{p}{n}\), where \(p\) is the number of variables and \(n\) is the number of observations of the random matrix.

• sigma (float, optional) – The standard deviation of the random matrix. The default is 1.0.

property max: float

property min: float

class ssd.distributions.InverseWignerSemicircle(sigma: float = 1.0)

Bases: WignerSemicircle

An inverse Wigner semicircle probability density function.

The Wigner semicircle (WS) distribution is a probability density function that describes the asymptotic distribution of the eigenvalues of a large symmetric random matrix with Gaussian entries. Given a matrix \(X\) of size \(n \times n\), where \(n \to \infty\), the WS distribution is defined as:

\[\mu(x) = \frac{1}{2 \pi \sigma^2} \sqrt{4 \sigma^2 - x^2} \mathbb{1}_{[-2 \sigma, 2 \sigma]}(x)\]

where \(\mathbb{1}_{[-2 \sigma, 2 \sigma]}(x)\) is the indicator function of the interval \([-2 \sigma, 2 \sigma]\).

Parameters:

sigma (float, optional) – The standard deviation of the Gaussian distribution (default is 1.0)

property max: float

property min: float

class ssd.distributions.MarchenkoPastur(L: float, sigma: float = 1.0)

Bases: BaseDistribution

A Marchenko-Pastur probability density function.

The Marchenko-Pastur (MP) distribution is a probability density function that describes the asymptotic distribution of the singular values of a large rectangular random matrix with Gaussian entries (i.e. the eigenvalues of the associated covariance matrix). Given a matrix \(X\) of size \(n \times p\), where \(n \to \infty\) and \(p \to \infty\), such that \(\lambda = \frac{p}{n} \in (0, 1)\), the MP distribution is defined as:

\[\mu(x) = \frac{1}{2 \pi \sigma^2} \frac{\sqrt{(\lambda_+ - x)(x - \lambda_-)}}{\lambda x} \mathbb{1}_{[x_-, x_+]}(x)\]

where

\[\lambda_+ = \sigma^2 (1 + \sqrt{\lambda})^2\]

and

\[\lambda_- = \sigma^2 (1 - \sqrt{\lambda})^2\]

are the upper and lower bounds of the function, respectively, and \(\mathbb{1}_{[x_-, x_+]}(x)\) is the indicator function of the interval \([x_-, x_+]\).

Parameters:

• L (float) – The ratio \(\lambda = \frac{p}{n}\), where \(p\) is the number of variables and \(n\) is the number of observations of the random matrix.

• sigma (float, optional) – The standard deviation of the random matrix. The default is 1.0.

property max: float

property min: float

class ssd.distributions.TranslatedInverseMarchenkoPastur(L: float, sigma: float = 1.0)

Bases: InverseMarchenkoPastur

An inverse Marchenko-Pastur probability density function with lowest eigenvalue at zero.

The Marchenko-Pastur (MP) distribution is a probability density function that describes the asymptotic distribution of the singular values of a large rectangular random matrix with Gaussian entries (i.e. the eigenvalues of the associated covariance matrix). Given a matrix \(X\) of size \(n \times p\), where \(n \to \infty\) and \(p \to \infty\), such that \(\lambda = \frac{p}{n} \in (0, 1)\), the MP distribution is defined as:

\[\mu(x) = \frac{1}{2 \pi \sigma^2} \frac{\sqrt{(\lambda_+ - x)(x - \lambda_-)}}{\lambda x} \mathbb{1}_{[x_-, x_+]}(x)\]

where

\[\lambda_+ = \sigma^2 (1 + \sqrt{\lambda})^2\]

and

\[\lambda_- = \sigma^2 (1 - \sqrt{\lambda})^2\]

are the upper and lower bounds of the function, respectively, and \(\mathbb{1}_{[x_-, x_+]}(x)\) is the indicator function of the interval \([x_-, x_+]\).

Parameters:

• L (float) – The ratio \(\lambda = \frac{p}{n}\), where \(p\) is the number of variables and \(n\) is the number of observations of the random matrix.

• sigma (float, optional) – The standard deviation of the random matrix. The default is 1.0.

property m2: float

property max: float

property min: float

class ssd.distributions.TranslatedMarchenkoPastur(L: float, sigma: float = 1.0)

Bases: MarchenkoPastur

A Marchenko-Pastur probability density function with lowest eigenvalue at zero.

The Marchenko-Pastur (MP) distribution is a probability density function that describes the asymptotic distribution of the singular values of a large rectangular random matrix with Gaussian entries (i.e. the eigenvalues of the associated covariance matrix). Given a matrix \(X\) of size \(n \times p\), where \(n \to \infty\) and \(p \to \infty\), such that \(\lambda = \frac{p}{n} \in (0, 1)\), the MP distribution is defined as:

\[\mu(x) = \frac{1}{2 \pi \sigma^2} \frac{\sqrt{(\lambda_+ - x)(x - \lambda_-)}}{\lambda x} \mathbb{1}_{[x_-, x_+]}(x)\]

where

\[\lambda_+ = \sigma^2 (1 + \sqrt{\lambda})^2\]

and

\[\lambda_- = \sigma^2 (1 - \sqrt{\lambda})^2\]

are the upper and lower bounds of the function, respectively, and \(\mathbb{1}_{[x_-, x_+]}(x)\) is the indicator function of the interval \([x_-, x_+]\).

Parameters:

• L (float) – The ratio \(\lambda = \frac{p}{n}\), where \(p\) is the number of variables and \(n\) is the number of observations of the random matrix.

• sigma (float, optional) – The standard deviation of the random matrix. The default is 1.0.

property l0: float

property max: float

property min: float

class ssd.distributions.WignerSemicircle(sigma: float = 1.0)

Bases: BaseDistribution

A Wigner semicircle probability density function.

The Wigner semicircle (WS) distribution is a probability density function that describes the asymptotic distribution of the eigenvalues of a large symmetric random matrix with Gaussian entries. Given a matrix \(X\) of size \(n \times n\), where \(n \to \infty\), the WS distribution is defined as:

\[\mu(x) = \frac{1}{2 \pi \sigma^2} \sqrt{4 \sigma^2 - x^2} \mathbb{1}_{[-2 \sigma, 2 \sigma]}(x)\]

where \(\mathbb{1}_{[-2 \sigma, 2 \sigma]}(x)\) is the indicator function of the interval \([-2 \sigma, 2 \sigma]\).

Parameters:

sigma (float, optional) – The standard deviation of the Gaussian distribution (default is 1.0)

property max: float

property min: float

ssd.ssd module

SSD - PDE

The PDE module contains the class for the differential equation encoding the behaviour of the renormalization group.

class ssd.ssd.SSD(dist: BaseDistribution, noise: float = 0.0, epsilon: float = 1e-09, bc: Dict[str, Dict | str | BCBase] | Dict | str | BCBase | Tuple[Dict | str | BCBase, Dict | str | BCBase] | BoundaryAxisBase | Sequence[Dict[str, Dict | str | BCBase] | Dict | str | BCBase | Tuple[Dict | str | BCBase, Dict | str | BCBase] | BoundaryAxisBase] = 'auto_periodic_neumann')

Bases: PDEBase

Stochastic Signal Detection (SSD)

Parameters:

• dist (BaseDistribution) – Distribution of the signal

• noise (float) – Noise intensity (default is 0.0)

• epsilon (float) – Small number to avoid division by zero (default is 1.e-9)

• bc (BoundariesData) – Boundary conditions (default is ‘auto_periodic_neumann’)

Raises:

ValueError – If the lower bound of the energy scale is negative

evolution_rate(state: ScalarField, t: float = 0) → ScalarField

Compute the evolution rate of the differential equation.

Parameters:

• state (ScalarField) – The state of the field

• t (float) – The current time (default is 0)

Returns:

The evolution rate of the field at the given time

Return type:

ScalarField

property expression: str

Return the expression for the PDE.

\[\dot{\bar{\mathcal{U_k^\prime}}}[\bar{\chi}] = - \mathrm{dim}_{\tau}(\bar{\mathcal{U_k^\prime}})\, \bar{\mathcal{U_k^\prime}}[\bar{\chi}] + \mathrm{dim}_{\tau}(\chi)\, \bar{\chi}\, \bar{\mathcal{U_k^{\prime\prime}}}[\bar{\chi}] -2 \frac{3\, \bar{\mathcal{U_k^{\prime\prime}}}[\bar{\chi}] + 2\, \bar{\chi}\, \bar{\mathcal{U_k^{\prime\prime\prime}}}[\bar{\chi}]}{(1 + \bar{\mu}^2)^2}\]

Utility functions

• ssd.utils.matrix module
  • create_bulk()
  • create_signal()
• ssd.utils.plots module
  • plot_inverse_mp_distribution()
  • plot_mp_distribution()
  • plot_potential()