FRG Tools

These tools enable the computation of the canonical dimensions and other properties of the Functional Renormalisation Group for data analysis. Specifically, they have been designed to efficiently perform the analysis of the signal-to-noise ratio in generic signals. The latter can be provided as either an “image” (i.e. a data matrix) or as a covariance matrix (in .npy format).

frg is a Python package to deal with the functional renormalisation group for signal detection. It leverages the action of the RG on different sources of signal to compute a limit of detection and assess the presence of a signal.

The work is based on theoretical advancements and previous numerical works and improvements.

class frg.EmpiricalDistribution(n_samples: int, var: float = 1.0, ratio: float = 0.5, is_poisson: bool = False, poisson_data: bool = False, poisson_lam: float = 10.0, poisson_centering: Literal['centered', 'non-centered', 'mirrored'] = 'centered', seed: int = 42)[source]

Bases: Distribution

The empirical distribution uses a Kernel Density Estimation (KDE) to fit the spectrum of the theory and analyse it.

Initialize the empirical distribution.

Parameters:

n_samples (int) – The number of samples in the distribution.
var (float) – The variance of the distribution.
ratio (float) –
The ratio between the number of variables and the dimension of the sample/population.

Note

Let \(X \in \mathbb{R}^{n \times p}\) be a real matrix where samples are row vectors, then the ratio parameter is \(\frac{p}{n}\).
is_poisson (bool) – Add Poisson noise (e.g. photon counting), by default False.
poisson_data (bool) – Whether to add Poisson noise directly to the data (if True) or to the covariance matrix (if False), by default False.
poisson_lam (float) – The rate parameter for the Poisson distribution, by default 10.0.
poisson_centering (Literal["centered", "non-centered", "mirrored"]) – The centering method for Poisson noise, by default "centered". Must be one of: - “centered”: Center the Poisson noise by removing the expected value from the generated sample. - “non-centered”: Do not center the Poisson noise. - “mirrored”: Mirror the Poisson noise by generating two samples and subtracting them (Skellam).
seed (int) – The random seed, by default 42.

Warns:

UserWarning – If the size of the sample is less than 1000 (sample too small)

add_signal(X: Float[np.ndarray, n_samples_sig, n_vars_sig], snr: float = 0.0) → EmpiricalDistribution[source]

Add a signal to the distribution.

Parameters:

X (ndarray of floats) – The signal to add (shape: \(n_S \times p_S\)). If \(n_S \neq n\) or \(p_S \neq p\), the signal matrix will be resized to match the background.
snr (float) – The signal-to-noise ratio, by default 0.0. If negative, then only signal is kept and noise is discarded.

Returns:

A new instance of the class with the signal added.

Return type:

EmpiricalDistribution

Warns:

UserWarning – If the distribution was created from a covariance matrix, adding a signal may lead to unexpected results.

Raises:

ValueError – If the signal matrix is not 2-dimensional.

canonical_dimensions(x: float | Float[np.ndarray, n_samples]) → Float[np.ndarray, 4] | Float[np.ndarray, n_samples, 4]

Compute the canonical dimensions of the distribution.

Notes

The method uses the following formulae:

\[\text{dim}_{u_2}(k^2) = \frac{\int^{k^2}_0 \mathrm{d}p^2 \rho(p^2)}{k^2 \rho(k^2)}\]

\[\text{dim}_{u_4}(k^2) = \text{dim}_{u_2}(k^2) \left( 3 + k^2 \frac{\partial \ln \rho(k^2)}{\partial k^2} - 2 \right)\]

\[\text{dim}_{u_6}(k^2) = -\text{dim}_{u_2}(k^2) + 2 \cdot \text{dim}_{u_4}(k^2)\]

\[\text{dim}_{\chi}(k^2)= 1 - \text{dim}_{u_2}(k^2)\]

Parameters:

x (float or ndarray of floats) – The value(s) at which to evaluate the canonical dimensions (shape: scalar or array of shape \(n\)).

Returns:

An array containing, in columns (shape: \(4\), if input is scalar, or \(n \times 4\), if input is array):

dim_u2: the mass term
dim_u4: the quartic interaction
dim_u6: the sextic interaction
dim_chi: the dimension of the field

Return type:

ndarray of floats

cdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples][source]

Compute the CDF of the eigenvalue distribution.

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the CDF (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the CDF at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats
Raises:: ValueError – If the distribution has not been fitted yet.

property data: Float[np.ndarray, n_samples, n_vars]

Return the data matrix.

Returns:: The data matrix (shape: \(n \times p\)).
Return type:: ndarray of floats

dipdf(x: float | Float[np.ndarray, n_samples], eps: float = 1e-06) → float | Float[np.ndarray, n_samples]

Compute the derivative of the PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

The derivative is computed using a central difference method:

\[f'(x) \approx \frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon}\]

Parameters:

x (float or ndarray of floats) – The value(s) at which to evaluate the derivative of the inverse PDF (shape: scalar or array of shape \(n\)).
eps (float) – The incremental ratio \(\epsilon\), by default \(10^{-9}\).

Returns:

The value(s) of the derivative of the inverse PDF at the given value(s) (shape: scalar or array of shape \(n\)).

Return type:

float or ndarray of floats

dlnipdf(x: float | Float[np.ndarray, n_samples], eps: float = 1e-06) → float | Float[np.ndarray, n_samples]

Compute the derivative of the natural log-PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

The derivative is computed using a central difference method:

\[f'(x) \approx \frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon}\]

Parameters:

x (float or ndarray of floats) – The value(s) at which to evaluate the derivative of the natural log-inverse PDF (shape: scalar or array of shape \(n\)).
eps (float) – The incremental ratio \(\epsilon\), by default \(10^{-9}\).

Returns:

The value(s) of the derivative of the natural log-inverse PDF at the given value(s) (shape: scalar or array of shape \(n\)).

Return type:

float or ndarray of floats

dpdf(x: float | Float[np.ndarray, n_samples], eps: float = 1e-06) → float | Float[np.ndarray, n_samples]

Compute the derivative of the PDF of a random variable \(X\) at given value(s) \(x\).

The derivative is computed using the finite difference method:

\[f'(x) \approx \frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon}\]

Parameters:

x (float or ndarray of floats) – The point(s) at which to compute the derivative of the PDF (shape: scalar or array of shape \(n\)).
eps (float) – The incremental ratio \(\epsilon\), by default \(10^{-9}\).

Returns:

The value(s) of the derivative of the PDF (shape: scalar or array of shape \(n\)).

Return type:

float or ndarray of floats

property eigenvalues: Float[np.ndarray, n_vars]

Compute the eigenvalues of the distribution.

Notes

This is the complete list of eigenvalues (bulk + spikes). You can access the filtered distribution without the spikes using the self.eigenvalues_ attribute, available after calling the self.fit(...) method.

Returns:: The eigenvalues of the distribution, sorted in ascending order (shape: \(p\)).
Return type:: ndarray of floats

find_spikes(eigenvalues: Float[np.ndarray, n_vars], pow: float = 0.5) → int[source]

Find the spikes in the eigenvalues.

The search for spikes is done by measuring the distance between eigenvalues from the IR to the UV. When eigenvalues start to form a continuous bulk (i.e. the difference between consecutive eigenvalues is smaller than a threshold), they are considered part of the bulk.

Parameters:

eigenvalues (ndarray of floats) – The eigenvalues of the distribution (shape: \(p\)).
pow (float) – Continuity criterion of the eigenvalues, by default 0.5.

Returns:

The index of the first spike (which equals the number of eigenvalues in the bulk).

Return type:

int

fit(X: Float[np.ndarray, n_samples, n_vars] | None = None, snr: float = 0.0, fac: float = 0.3) → EmpiricalDistribution[source]

Add the signal (if provided) and compute the eigenvalue distribution.

Parameters:

X (ndarray of floats, optional) – The signal to add (shape: \(n \times p\)).
snr (float) – The signal-to-noise ratio.
fac (float) – Bandwidth factor. By deault 0.3.

Returns:

A new instance of the class with the signal added and the eigenvalue distribution computed.

Return type:

EmpiricalDistribution

frg_equations(x: float, u2_init: float, u4_init: float, u6_init: float, dx: float = 1e-09, x_ir: float = 0.0, use_naive_euler: bool = True) → Float[np.ndarray, n_steps, 4]

Compute the FRG equations.

Given initial conditions of the couplings \(u_2\), \(u_4\), and \(u_6\) at a given momentum scale \(k^2\), the function returns the values of the couplings at the scale \(k^2 - \Delta_k\). That is, the function returns the running of the couplings from the UV region towards the IR (\(k^2 \to 0\)):

\[\dot{u}_2 = - \text{dim}_{u_2} u_2 - 2 \frac{u_4}{(1 + u_2)^2}\]

\[\dot{u}_4 = - \text{dim}_{u_4} u_4 - 2 \frac{u_6}{(1 + u_2)^2} + 12 \frac{u_4^2}{(1 + u_2)^3}\]

\[\dot{u}_6 = - \text{dim}_{u_6} u_6 + 60 \frac{u_4 u_6}{(1 + u_2)^3} - 108 \frac{u_6^3}{(1 + u_2)^4}\]

Parameters:

x (float) – The momentum scale \(k^2\) at which to start computing the FRG equations. This represents an energy scale in the UV region. The FRG computation ends in the IR region.
u2_init (float) – The initial value of the coupling \(u_2\) at energy scale \(x\).
u4_init (float) – The initial value of the coupling \(u_4\) at energy scale \(x\).
u6_init (float) – The initial value of the coupling \(u_6\) at energy scale \(x\).
dx (float) – The step size, by default 1.0e-9.
x_ir (float) – The definition of IR scale (i.e. the scale \(k^2\) to be considered low-energy), by default 0.0. It can be overridden to match physical assumptions (e.g. histogram binning, etc.).
use_naive_euler (bool) – Whether to use the naive Euler method for integration, by default True. If False, a more sophisticated integration method will be used.

Returns:

An array containing, in columns (shape: \(S \times 4\) where \(S\) is the number of steps):

k2: the energy scale corresponding to the couplings
u2: the running of the coupling \(u_2\)
u4: the running of the coupling \(u_4\)
u6: the running of the coupling \(u_6\)

The number of computed steps is:

\[S = \lfloor \frac{x - x_{\text{IR}}}{\Delta x} \rfloor\]

Return type:

ndarray of floats

frg_equations_lpa(x: float, kappa_init: float, u4_init: float, u6_init: float, dx: float = 1e-09, x_ir: float = 0.0, use_naive_euler: bool = True) → Float[np.ndarray, n_steps, 4]

Compute the FRG equations (LPA).

Given initial conditions of the zero of the potential \(\kappa\) and the couplings \(u_2\), and \(u_4\) at a given momentum scale \(k^2\), the function returns the values of the couplings at the scale \(k^2 - \Delta_k\) in Local Potential Approximation (LPA). That is, the function returns the running of the couplings from the UV region towards the IR (\(k^2 \to 0\)):

\[\dot{\kappa} = - \text{dim}_{\chi} \kappa + 2 \frac{3 + 2 \kappa \frac{u_6}{u_4}}{(1 + 2 \kappa u_4)^2}\]

\[\dot{u}_4 = - \text{dim}_{u_4} u_4 + \text{dim}_{\chi} \kappa u_6 - 10 \frac{u_6}{(1 + 2 \kappa u_4)^2} + 4 \frac{(3 u_4 + 2 \kappa u_6)^2}{(1 + 2 \kappa u_4)^3}\]

\[\dot{u}_6 = - \text{dim}_{u_6} u_6 - 12 \frac{(3 u_4 + 2 \kappa u_6)^3}{(1 + 2 \kappa u_4)^4} + 40 \frac{u_6 (3 u_4 + 2 \kappa u_6)}{(1 + 2 \kappa u_4)^2}\]

Parameters:

x (float) – The momentum scale \(k^2\) at which to start computing the FRG equations. This represents an energy scale in the UV region. The FRG computation ends in the IR region.
kappa_init (float) – The initial value of the position of the zero of the potential \(\kappa\) at energy scale \(x\).
u4_init (float) – The initial value of the coupling \(u_4\) at energy scale \(x\).
u6_init (float) – The initial value of the coupling \(u_6\) at energy scale \(x\).
dx (float) – The step size, by default 1.0e-9.
x_ir (float) – The definition of IR scale (i.e. the scale \(k^2\) to be considered low-energy), by default 0.0. It can be overridden to match physical assumptions (e.g. histogram binning, etc.).
use_naive_euler (bool) – Whether to use the naive Euler method for integration, by default True. If False, a more sophisticated integration method will be used.

Returns:

An array containing, in columns (shape: \(S \times 4\) where \(S\) is the number of steps):

k2: the energy scale corresponding to the couplings
kappa: the running of the zero of the potential \(\kappa\)
u4: the running of the coupling \(u_4\)
u6: the running of the coupling \(u_6\)

The number of computed steps is:

\[S = \lfloor \frac{x - x_{\text{IR}}}{\Delta x} \rfloor\]

Return type:

ndarray of floats

classmethod from_config(cfg: CfgNode) → EmpiricalDistribution[source]

Create an instance of the class from a configuration.

Parameters:: cfg (CfgNode) – The configuration.
Returns:: An instance of the class.
Return type:: EmpiricalDistribution

classmethod from_covariance(cov: Float[np.ndarray, n_samples, n_vars], cfg: CfgNode) → EmpiricalDistribution[source]

Create an instance of the class from a covariance matrix.

Parameters:

cov (ndarray of floats) – The covariance matrix (shape: \(n \times p\)).
cfg (CfgNode) – The configuration

Returns:

An instance of the class.

Return type:

EmpiricalDistribution

icdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples][source]

Compute the CDF of the distribution of the inverse of the eigenvalues.

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the CDF of the momenta (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the CDF of the momenta (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats
Raises:: ValueError – If the distribution has not been fitted yet.

ipdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples]

Compute the PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the PDF of the inverse variable (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the PDF of the inverse variable at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats

lnipdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples]

Compute the natural log-PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the log-PDF of the inverse variable (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the log-PDF of the inverse variable at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats

pdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples][source]

Compute the value of the Probability Density Function (PDF) of the eigenvalue distribution at given value(s) \(x\).

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the PDF (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the PDF at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats
Raises:: ValueError – If the distribution has not been fitted yet.

class frg.MarchenkoPastur(ratio: float, var: float)[source]

Bases: Distribution

The Marchenko-Pastur distribution represents the distribution of eigenvalues of large random covariance matrices.

Initialize the Marchenko-Pastur distribution.

Parameters:

ratio (float) –
The ratio between the number of variables and the dimension of the sample/population.

Note

Let \(X \in \mathbb{R}^{n \times p}\) be a real matrix where samples are row vectors, then the ratio parameter is \(\frac{p}{n}\).
var (float) – The variance of the distribution.

Warns:

UserWarning – If ratio is higher than 1 because of numerical instabilities

Raises:

ValueError – If ratio is not strictly positive
ValueError – If the lowest eigenvalue is higher than the highest one

canonical_dimensions(x: float | Float[np.ndarray, n_samples]) → Float[np.ndarray, 4] | Float[np.ndarray, n_samples, 4]

Compute the canonical dimensions of the distribution.

Notes

The method uses the following formulae:

\[\text{dim}_{u_2}(k^2) = \frac{\int^{k^2}_0 \mathrm{d}p^2 \rho(p^2)}{k^2 \rho(k^2)}\]

\[\text{dim}_{u_4}(k^2) = \text{dim}_{u_2}(k^2) \left( 3 + k^2 \frac{\partial \ln \rho(k^2)}{\partial k^2} - 2 \right)\]

\[\text{dim}_{u_6}(k^2) = -\text{dim}_{u_2}(k^2) + 2 \cdot \text{dim}_{u_4}(k^2)\]

\[\text{dim}_{\chi}(k^2)= 1 - \text{dim}_{u_2}(k^2)\]

Parameters:

x (float or ndarray of floats) – The value(s) at which to evaluate the canonical dimensions (shape: scalar or array of shape \(n\)).

Returns:

An array containing, in columns (shape: \(4\), if input is scalar, or \(n \times 4\), if input is array):

dim_u2: the mass term
dim_u4: the quartic interaction
dim_u6: the sextic interaction
dim_chi: the dimension of the field

Return type:

ndarray of floats

cdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples][source]

Compute the CDF of the Marchenko-Pastur distribution.

Parameters:: x (float | np.ndarray) – The value(s) at which to evaluate the CDF.
Returns:: The value(s) of the CDF at the given value(s).
Return type:: float | np.ndarray

dipdf(x: float | Float[np.ndarray, n_samples], eps: float = 1e-06) → float | Float[np.ndarray, n_samples]

Compute the derivative of the PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

The derivative is computed using a central difference method:

\[f'(x) \approx \frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon}\]

Parameters:

x (float or ndarray of floats) – The value(s) at which to evaluate the derivative of the inverse PDF (shape: scalar or array of shape \(n\)).
eps (float) – The incremental ratio \(\epsilon\), by default \(10^{-9}\).

Returns:

The value(s) of the derivative of the inverse PDF at the given value(s) (shape: scalar or array of shape \(n\)).

Return type:

float or ndarray of floats

dlnipdf(x: float | Float[np.ndarray, n_samples], eps: float = 1e-06) → float | Float[np.ndarray, n_samples]

Compute the derivative of the natural log-PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

The derivative is computed using a central difference method:

\[f'(x) \approx \frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon}\]

Parameters:

x (float or ndarray of floats) – The value(s) at which to evaluate the derivative of the natural log-inverse PDF (shape: scalar or array of shape \(n\)).
eps (float) – The incremental ratio \(\epsilon\), by default \(10^{-9}\).

Returns:

The value(s) of the derivative of the natural log-inverse PDF at the given value(s) (shape: scalar or array of shape \(n\)).

Return type:

float or ndarray of floats

dpdf(x: float | Float[np.ndarray, n_samples], eps: float = 1e-06) → float | Float[np.ndarray, n_samples]

Compute the derivative of the PDF of a random variable \(X\) at given value(s) \(x\).

The derivative is computed using the finite difference method:

\[f'(x) \approx \frac{f(x + \epsilon) - f(x - \epsilon)}{2 \epsilon}\]

Parameters:

x (float or ndarray of floats) – The point(s) at which to compute the derivative of the PDF (shape: scalar or array of shape \(n\)).
eps (float) – The incremental ratio \(\epsilon\), by default \(10^{-9}\).

Returns:

The value(s) of the derivative of the PDF (shape: scalar or array of shape \(n\)).

Return type:

float or ndarray of floats

frg_equations(x: float, u2_init: float, u4_init: float, u6_init: float, dx: float = 1e-09, x_ir: float = 0.0, use_naive_euler: bool = True) → Float[np.ndarray, n_steps, 4]

Compute the FRG equations.

Given initial conditions of the couplings \(u_2\), \(u_4\), and \(u_6\) at a given momentum scale \(k^2\), the function returns the values of the couplings at the scale \(k^2 - \Delta_k\). That is, the function returns the running of the couplings from the UV region towards the IR (\(k^2 \to 0\)):

\[\dot{u}_2 = - \text{dim}_{u_2} u_2 - 2 \frac{u_4}{(1 + u_2)^2}\]

\[\dot{u}_4 = - \text{dim}_{u_4} u_4 - 2 \frac{u_6}{(1 + u_2)^2} + 12 \frac{u_4^2}{(1 + u_2)^3}\]

\[\dot{u}_6 = - \text{dim}_{u_6} u_6 + 60 \frac{u_4 u_6}{(1 + u_2)^3} - 108 \frac{u_6^3}{(1 + u_2)^4}\]

Parameters:

x (float) – The momentum scale \(k^2\) at which to start computing the FRG equations. This represents an energy scale in the UV region. The FRG computation ends in the IR region.
u2_init (float) – The initial value of the coupling \(u_2\) at energy scale \(x\).
u4_init (float) – The initial value of the coupling \(u_4\) at energy scale \(x\).
u6_init (float) – The initial value of the coupling \(u_6\) at energy scale \(x\).
dx (float) – The step size, by default 1.0e-9.
x_ir (float) – The definition of IR scale (i.e. the scale \(k^2\) to be considered low-energy), by default 0.0. It can be overridden to match physical assumptions (e.g. histogram binning, etc.).
use_naive_euler (bool) – Whether to use the naive Euler method for integration, by default True. If False, a more sophisticated integration method will be used.

Returns:

An array containing, in columns (shape: \(S \times 4\) where \(S\) is the number of steps):

k2: the energy scale corresponding to the couplings
u2: the running of the coupling \(u_2\)
u4: the running of the coupling \(u_4\)
u6: the running of the coupling \(u_6\)

The number of computed steps is:

\[S = \lfloor \frac{x - x_{\text{IR}}}{\Delta x} \rfloor\]

Return type:

ndarray of floats

frg_equations_lpa(x: float, kappa_init: float, u4_init: float, u6_init: float, dx: float = 1e-09, x_ir: float = 0.0, use_naive_euler: bool = True) → Float[np.ndarray, n_steps, 4]

Compute the FRG equations (LPA).

Given initial conditions of the zero of the potential \(\kappa\) and the couplings \(u_2\), and \(u_4\) at a given momentum scale \(k^2\), the function returns the values of the couplings at the scale \(k^2 - \Delta_k\) in Local Potential Approximation (LPA). That is, the function returns the running of the couplings from the UV region towards the IR (\(k^2 \to 0\)):

\[\dot{\kappa} = - \text{dim}_{\chi} \kappa + 2 \frac{3 + 2 \kappa \frac{u_6}{u_4}}{(1 + 2 \kappa u_4)^2}\]

\[\dot{u}_4 = - \text{dim}_{u_4} u_4 + \text{dim}_{\chi} \kappa u_6 - 10 \frac{u_6}{(1 + 2 \kappa u_4)^2} + 4 \frac{(3 u_4 + 2 \kappa u_6)^2}{(1 + 2 \kappa u_4)^3}\]

\[\dot{u}_6 = - \text{dim}_{u_6} u_6 - 12 \frac{(3 u_4 + 2 \kappa u_6)^3}{(1 + 2 \kappa u_4)^4} + 40 \frac{u_6 (3 u_4 + 2 \kappa u_6)}{(1 + 2 \kappa u_4)^2}\]

Parameters:

x (float) – The momentum scale \(k^2\) at which to start computing the FRG equations. This represents an energy scale in the UV region. The FRG computation ends in the IR region.
kappa_init (float) – The initial value of the position of the zero of the potential \(\kappa\) at energy scale \(x\).
u4_init (float) – The initial value of the coupling \(u_4\) at energy scale \(x\).
u6_init (float) – The initial value of the coupling \(u_6\) at energy scale \(x\).
dx (float) – The step size, by default 1.0e-9.
x_ir (float) – The definition of IR scale (i.e. the scale \(k^2\) to be considered low-energy), by default 0.0. It can be overridden to match physical assumptions (e.g. histogram binning, etc.).
use_naive_euler (bool) – Whether to use the naive Euler method for integration, by default True. If False, a more sophisticated integration method will be used.

Returns:

An array containing, in columns (shape: \(S \times 4\) where \(S\) is the number of steps):

k2: the energy scale corresponding to the couplings
kappa: the running of the zero of the potential \(\kappa\)
u4: the running of the coupling \(u_4\)
u6: the running of the coupling \(u_6\)

The number of computed steps is:

\[S = \lfloor \frac{x - x_{\text{IR}}}{\Delta x} \rfloor\]

Return type:

ndarray of floats

icdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples]

Compute the CDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the CDF of the inverse variable (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the CDF of the inverse variable at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats

ipdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples]

Compute the PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the PDF of the inverse variable (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the PDF of the inverse variable at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats

lnipdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples]

Compute the natural log-PDF of the inverse of the random variable \(X\) (i.e. \(Y = 1 / X\)) at given value(s) \(x\).

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the log-PDF of the inverse variable (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the log-PDF of the inverse variable at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats

pdf(x: float | Float[np.ndarray, n_samples]) → float | Float[np.ndarray, n_samples][source]

Compute the PDF of the Marchenko-Pastur distribution.

Notes

The PDF uses this mathematical formula:

\[\mu_{\text{MP}}(x) = \frac{\sqrt{(\lambda_+ - x)(x - \lambda_-)}}{2 \pi \sigma^2 q \, x},\]

where

\[\lambda_{\pm} = \sigma^2 (1 \pm \sqrt{q})^2,\]

and

\[q = \frac{p}{n}.\]

Parameters:: x (float or ndarray of floats) – The value(s) at which to evaluate the PDF (shape: scalar or array of shape \(n\)).
Returns:: The value(s) of the PDF at the given value(s) (shape: scalar or array of shape \(n\)).
Return type:: float or ndarray of floats

frg.add_values(interp_values: tuple[float, float, float, float], scale: list[float], dimu2: list[float], dimu4: list[float], dimu6: list[float]) → None[source]

Add values to lists.

Parameters:

interp_values (tuple[float, float, float, float]) – The interpolated values of \(k^2\), \(\text{dim}(u_{2})\), \(\text{dim}(u_{4})\), \(\text{dim}(u_{6})\).
scale (list[float]) – The list of values of the reference scale \(k^2\).
dimu2 (list[float]) – The list of values of \(\text{dim}(u_{2})\).
dimu4 (list[float]) – The list of values of \(\text{dim}(u_{4})\).
dimu6 (list[float]) – The list of values of \(\text{dim}(u_{6})\).

frg.canonical_dimensions_argsort(x: Float[np.ndarray, n] | list[float], dimu2: Float[np.ndarray, n] | list[float], dimu4: Float[np.ndarray, n] | list[float], dimu6: Float[np.ndarray, n] | list[float]) → tuple[Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n]][source]

Index sort the signal to noise ratio and the canonical dimensions.

Parameters:

x (array of floats) – The quantity of interest (shape: \(n\)).
dimu2 (array of floats) – The canonical dimension of the quadratic coupling (shape: \(n\)).
dimu4 (array of floats) – The canonical dimension of the quartic coupling (shape: \(n\)).
dimu6 (array of floats) – The canonical dimension of the sextic coupling (shape: \(n\)).

Returns:

A tuple containing the signal-to-noise ratio and the canonical dimensions in the same order as the input parameters.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

frg.canonical_dimensions_files(path: str | Path, glob: str = '*.json', analytic: bool = False) → tuple[Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n]][source]

Open multiple files and stores the canonical dimensions.

Parameters:

path (str | Path) – The path to the directory containing the files.
glob (str) – The global pattern to open. By default “*.json”.
analytic (bool) – Treat the experiment as analytic. By default False.

Returns:

A tuple containing the quantity of interest, and the canonical dimensions.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

frg.canonical_dimensions_files_poiss(path: str | Path, glob: str = '*.json') → tuple[Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n], Float[np.ndarray, n]][source]

Open multiple files and stores the canonical dimensions in case of Poisson noise.

Parameters:

path (str | Path) – The path to the directory containing the files.
glob (str) – The global pattern to open. By default “*.json”.

Returns:

A tuple containing the Gaussian signal-to-noise ratio, the Poisson parameter, and the canonical dimensions.

Return type:

tuple[np.ndarray,np.ndarray, np.ndarray, np.ndarray, np.ndarray]

frg.canonical_dimensions_ratio_files(path: str | Path, glob: str = '*.json', analytic: bool = False) → DataFrame[source]

Open multiple files as a function of ratio and seed and stores the canonical dimensions.

Parameters:

path (str | Path) – The path to the directory containing the files.
glob (str) – The global pattern to open. By default “*.json”.
analytic (bool) – Treat the experiment as analytic. By default False.

Returns:

A dataframe containing the ratio, the seed, and the canonical dimensions.

Return type:

pd.DataFrame

frg.compute_roi(data: dict[str, Any], thresh: float = 0.5, analytic: bool = False) → tuple[int, int, int][source]

Compute the indices of the region of interest, and its initial and final points.

Parameters:

data (dict[str, Any]) – The results of the computation of the canonical dimensions.
thresh (float) – The value of the threshold on the distribution to be considered “bulk”. By default 0.5.
analytic (bool) – Treat the distribution as analytic. By default False.

Returns:

The point of interest, the start of the region of interest, the end of the region of interest

Return type:

tuple[int, int, int]

frg.direct_relative_adherence(data: dict[str, Any], thresh: float = 0.5, suffix: str | None = None, output_dir: str | Path = 'plots') → None[source]

Compute the direct relative adherence.

Parameters:

data (dict[str, Any]) – The results of the computation of the canonical dimensions.
thresh (float) – The value of the threshold on the distribution to be considered “bulk”. By default 0.5.
suffix (str, optional) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.

frg.extract_interp_values(data: dict[str, Any], thresh: float = 0.5, deep_ir: bool = False) → tuple[float, float, float, float][source]

Extract the interpolated values.

Parameters:

data (dict[str, Any]) – The experimental data.
thresh (float) – The value of the threshold on the distribution to be considered “bulk”. By default 0.5.
deep_ir (bool) – Return the values of the interpolation at the deep IR scale. By default False.

Returns:

The values of \(k^2\), \(\text{dim}(u_{2})\), \(\text{dim}(u_{4})\), and \(\text{dim}(u_{6})\) at the reference scale.

Return type:

tuple[float, float, float, float]

frg.get_cfg_defaults() → CfgNode[source]

Get the default configuration.

Returns:: The default configuration (YACS CfgNode)
Return type:: CfgNode

frg.get_logger(name: str, level: int = 10) → Logger[source]

Get the logger.

Parameters:

name (str) – The name of the logger (logging session)
level (int) –
The logging level:
- logging.DEBUG = 10
- logging.INFO = 20
- logging.WARNING = 30
- logging.ERROR = 40
- logging.CRITICAL = 50

Returns:

The logger

Return type:

logging.Logger

frg.interp_canonical_dimensions(data: dict[str, Any], idx: int) → tuple[Callable, Callable, Callable][source]

Interpolate the behaviour of the canonical dimensions.

Parameters:

data (dict[str, Any]) – The experimental data.
idx (int) – The index of the starting point.

Returns:

The interpolated canonical dimensions.

Return type:

tuple[Callable, Callable, Callable]

frg.load_data(cfg: CfgNode) → EmpiricalDistribution[source]

Load the data from file.

Parameters:

cfg (CN) – The configuration file.
warning:: (..) – The image must be a B/W image (single channel) and present pixels in the range \([0, 255]\).

Returns:

The distribution

Return type:

EmpiricalDistribution

Raises:

FileNotFoundError – If the input data file does not exist.
ValueError – If the input data file is not in the expected format.

frg.plot_canonical_dimensions(data: dict[str, Any], thresh: float = 0.5, suffix: str | None = None, analytic: bool = False, output_dir: str | Path = 'plots', ratio: float | None = None, var: float | None = None) → None[source]

Plot a single instance of the canonical dimensions.

Parameters:

data (dict[str, Any]) – The results of the computation of the canonical dimensions.
thresh (float) – The value of the threshold on the distribution to be considered “bulk”. By default 0.5.
suffix (str, optional) – The suffix of the file name.
analytic (bool) – Analytic computation. By default False.
output_dir (str | Path) – The output directory. By default “plots”.
ratio (float, optional) – Marchenko-Pastur ratio \(q = p/n\). If provided together with var, displayed as the legend title.
var (float, optional) – Marchenko-Pastur variance \(\\sigma^2\). If provided together with ratio, displayed as the legend title.

frg.plot_canonical_dimensions_eigenvalues(data: dict[str, Any], dist: Distribution, thresh: float = 0.5, suffix: str | None = None, analytic: bool = False, output_dir: str | Path = 'plots') → None[source]

Plot a single instance of the canonical dimensions on the eigenvalue spectrum.

The momentum scale \(k^2\) is mapped back to the eigenvalue axis \(\lambda\) via the inverse of the change of variables used in ipdf():

\[\lambda = \frac{1}{k^2 + m^2} + \lambda_-\]

where \(m^2\) is the mass (inverse of the largest eigenvalue) and \(\lambda_-\) is the smallest eigenvalue of the distribution.

Parameters:

data (dict[str, Any]) – The results of the computation of the canonical dimensions (as produced by the canonical-dimensions scripts). Expected keys: "k2", "dimu2", "dimu4", "dimu6".
dist (Distribution) – The distribution instance used to perform the computation. Its m2 and lminus attributes define the variable transformation, and its pdf method is used to draw the eigenvalue PDF on a twin axis.
thresh (float) – The value of the threshold on the distribution to be considered “bulk”. By default 0.5.
suffix (str, optional) – The suffix of the output file name.
analytic (bool) – Analytic computation. By default False.
output_dir (str | Path) – The output directory. By default "plots".

Plot the canonical dimensions as a function of a particular quantity of interest.

Parameters:

x (array of floats) – The quantity of interest (shape: \(n\)).
name (str) – The label of the x-axis.
win (int) – The smoothing window width. By default 0.
dimu2 (array of floats, optional) – The list of values of the canonical dimension of the quadratic coupling (shape: \(n\)).
dimu4 (array of floats, optional) – The list of values of the canonical dimension of the quartic coupling (shape: \(n\)).
dimu6 (array of floats, optional) – The list of values of the canonical dimension of the sextic coupling (shape: \(n\)).
suffix (str, optional) – The suffix to postpone to the file name.
image (str | Path, optional) – The path to the image used for the computations.
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_canonical_dimensions_scan2d(snr: Float[np.ndarray, n], lam: Float[np.ndarray, n], dimu2: Float[np.ndarray, n], dimu4: Float[np.ndarray, n], dimu6: Float[np.ndarray, n], suffix: str | None = None, image: str | None = None, output_dir: str | Path = 'plots')[source]

Plot the canonical dimensions as a surface plot of the signal-to-noise ratio and the Poisson parameter.

Parameters:

snr (array of floats) – The signal-to-noise ratio (shape: \(n\)).
lam (array of floats) – The Poisson parameter (shape: \(n\)).
dimu2 (array of floats, optional) – The list of values of the canonical dimension of the quadratic coupling (shape: \(n\)).
dimu4 (array of floats, optional) – The list of values of the canonical dimension of the quartic coupling (shape: \(n\)).
dimu6 (array of floats, optional) – The list of values of the canonical dimension of the sextic coupling (shape: \(n\)).
suffix (str, optional) – The suffix to postpone to the file name.
image (str | Path, optional) – The path to the image used for the computations.
output_dir (str | Path) – The output directory. By default “plots”.

Raises:

FileNotFoundError – If the provided image could not be found.

frg.plot_distribution(dist: Distribution, output_dir: str | Path = 'plots') → None[source]

Plot distributions.

Parameters:

dist (Distribution) – The distribution to show.
output_dir (str | Path) – The output directory of the plots. By default “plots”.

frg.plot_eigenvalues(data: dict[str, Any], suffix: str | None = None, zoom: bool = False, output_dir: str | Path = 'plots') → None[source]

Plot the eigenvalues of the distribution.

Parameters:

data (dict[str, Any]) – The eigenvalues and eigenvectors.
suffix (str) – The name to postpone to the file name.
zoom (bool) – Add an inset axis to zoom on the IR region. By default False.
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_localization(data: dict[str, Any], suffix: str | None = None, output_dir: str | Path = 'plots') → tuple[float, float, float, float, float][source]

Plot the localization of the components of the eigenvectors in the UV and IR.

Parameters:

data (dist[str, Any]) – The eigenvalues and eigenvectors.
suffix (str) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.

Returns:

The values of:

the ratio of the histograms at the average value of the UV (0.0),
the average value of the UV distribution,
the standard deviation of the UV distribution.
the average value of the IR distribution,
the standard deviation of the IR distribution.

Return type:

tuple[float, float, float, float, float]

frg.plot_localization_scan(snrs: list[float] | Float[np.ndarray, n], ratios: list[float] | Float[np.ndarray, n], uv_stds: list[float] | Float[np.ndarray, n], ir_means: list[float] | Float[np.ndarray, n], ir_stds: list[float] | Float[np.ndarray, n], output_dir: str | Path = 'plots') → None[source]

Plot values of the localization of the eigenvector components as a functions of the signal-to-noise ratio.

Parameters:

snrs (array of floats) – The list of the signal-to-noise ratio values (shape: \(n\)).
ratios (array of floats) – The list of ratios at the average of the UV distributions (shape: \(n\)).
uv_stds (array of floats) – The standard deviations of the UV distribution (shape: \(n\)).
ir_means (array of floats) – The mean values of the IR distribution (shape: \(n\)).
ir_stds (array of floats) – The standard deviations of the IR distribution (shape: \(n\)).
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_potential(x: Float[np.ndarray, n], u2: dict[float, list[float]], u4: dict[float, list[float]], n: int, suffix: str | None = None, output_dir: str | Path = 'plots') → None[source]

Plot the potential.

Parameters:

x (array of floats) – The list of point to be evaluated (shape: \(n\)).
u2 (dict[float, list[float]]) – A collection of quadratic couplings per SNR.
u4 (dict[float, list[float]]) – A collection of quartic couplings per SNR.
n (int) – The index of the sample to consider.
suffix (str) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_ratio_scan(groups: DataFrame, suffix: str | None = None, output_dir: str | Path = 'plots') → None[source]

Plot the canonical dimensions as a function of a particular quantity of interest.

Parameters:

groups (pd.DataFrame) – The grouped dataframe containing the points to plot.
suffix (str) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_symmetry_size(sizes: dict[str, float], suffix: str | None = None, output_dir: str | Path = 'plots') → None[source]

Plot the relative size of the symmetric phase.

Parameters:

sizes (dict[str, float]) – A collection containing the SNR as key and the relative size of the symmetric region as values.
suffix (str) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_symmetry_surface(phases_ir: list[int] | Integer[np.ndarray, n], u2: Float[np.ndarray, n], u4: Float[np.ndarray, n], u6: Float[np.ndarray, n], phases_uv: list[int] | Integer[np.ndarray, n] | None = None, suffix: str | None = None, output_dir: str | Path = 'plots') → None[source]

Plot the symmetry surface of the FRG equations.

Parameters:

phases_ir (list[int] or array of ints) – The classification of the phase in the IR region (1 is symmetric, 0 is broken symmetry).
u2 (array of floats) – The list of values of the quadratic coupling (shape: \(n\)).
u4 (array of floats) – The list of values of the quartic coupling (shape: \(n\)).
u6 (array of floats) – The list of values of the sextic coupling (shape: \(n\)).
phases_uv (list[int] or array of ints, optional) – The classification of the phase in the UV region (1 is symmetric, 0 is broken symmetry).
suffix (str) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.

frg.plot_trajectories(data: dict[str, Any], suffix: str | None = None, output_dir: str | Path = 'plots') → None[source]

Plot the FRG trajectories.

Parameters:

data (dict[str, Any]) – The list of the signal-to-noise ratio values.
suffix (str) – The name to postpone to the file name.
output_dir (str | Path) – The output directory. By default “plots”.