lucid Namespace Reference

Root namespace for the lucid library. More...

Namespaces
namespace	constants
	Constants values used in the lucid library.
namespace	exception
	Collection of exceptions that can be thrown by lucid.
namespace	internal
	Internal implementation details for Eigen extensions.
namespace	log
	Collection of logging utilities.
namespace	metrics
	Collection of metric measuring functions.
namespace	plt
	Lucid's matplotlib wrapper.
namespace	random
	Collection of random functions.
namespace	scorer
	Collection of utilities used to score the accuracy of estimators.
namespace	verification
	Collection of utilities used to verify whether the system abides by the given specifications.

Classes
class	AlglibOptimiser
	Linear optimiser using the Alglib mathematical library. More...
class	BarrierCertificate
	Control barrier certificates (CBCs) are often used to certify the safety of a stochastic systems. More...
class	BaseScopedValue
	Base class for creating a stack of scoped values of type T, identified by Tags. More...
class	Configuration
	Simple dataclass used to store the configuration of the program. More...
class	ConstantTruncatedFourierFeatureMap
	Truncated Fourier feature map using fixed intervals between each interval of the normal distribution. More...
class	CrossValidator
	During cross-validation, the available data is split into k folds. More...
class	EllipseSet
	Multidimensional ellipsoid set. More...
class	Estimator
	Given two vector spaces, \( \texttip{\mathcal{X}}{Polish sample vector space} \subseteq \mathbb{R}^{d_x} \) and \( \texttip{\mathcal{Y}}{Polish sample vector space} \subseteq \mathbb{R}^{d_y} \), and a map \( f: \mathcal{X} \to \mathcal{Y} \), the Estimator's goal is to produce a model \( f^*:\mathcal{X} \to \mathcal{Y} \) that best approximates \( f \). More...
class	FeatureMap
	Map input vectors to a feature space. More...
class	FourierBarrierCertificate
	Barrier certificate using a Fourier basis as a template for the function. More...
struct	FourierBarrierCertificateParameters
	Parameters for the Fourier barrier certificate synthesis using PSO. More...
struct	FourierBarrierSynthesisProblem
	LP problem to solver to achieve the Fourier barrier synthesis. More...
class	GaussianKernel
	RKHS Gaussian kernel. More...
class	GradientOptimizable
	Interface for objects that can be optimised using gradient-based methods (e.g., LbfgsTuner). More...
class	GramMatrix
	Gram Matrix obtained from a kernel function. More...
class	GridSearchTuner
	Grid search tuning strategy for model hyperparameter optimisation. More...
class	GurobiOptimiser
	Linear optimiser using the Gurobi solver. More...
class	HighsOptimiser
	Linear optimiser using the HiGHS mathematical library. More...
class	IndexIterator
	Iterator over all possible indexes in a given range. More...
class	InverseGramMatrix
	The inverse of a Gram matrix, \( K^{-1} \), allowing transparent multiplication with vectors and matrices. More...
class	Kernel
	Represents a kernel function. More...
class	KernelRidgeRegressor
	Ridge regressor with a kernel function. More...
class	KFold
	Generic K-Fold cross-validation, where the dataset is divided into k folds. More...
struct	LbfgsParameters
	Structure copied from lbfgscpp, to avoid a transitive dependency on the external library in the header. More...
class	LbfgsTuner
	Optimiser that uses the L-BFGS algorithm. More...
class	LeaveOneOut
	Leave-One-Out cross-validation (LOOCV) is a specific type of cross-validation where the number of folds equals the number of data points in the dataset. More...
class	LinearTruncatedFourierFeatureMap
	Truncated Fourier feature map using same-sized intervals between each interval of the normal distribution, from the origin to 3 standard deviations on each side. More...
class	LogTruncatedFourierFeatureMap
	Truncated Fourier feature map using log-sized intervals between each interval of the normal distribution, from the origin to 3 standard deviations on each side. More...
class	MedianHeuristicTuner
	Tuner that adjusts the kernel parameters using the median heuristic method. More...
class	ModelEstimator
	Dummy estimator that uses a user-defined function to make predictions. More...
class	MontecarloSimulation
	Monte Carlo simulation for estimating the safety probability of a system. More...
class	MultiSet
	Set composed of the union of multiple sets. More...
class	Optimiser
	Base class for optimisation solvers. More...
class	ParameterValue
	Parameter value used in a configurable system or application. More...
class	ParameterValues
	Collection of parameter values used in a configurable system or application. More...
class	Parametrizable
	Interface for objects that allow setting and getting parameters dynamically. More...
class	PolymorphicScopedValue
	Generic scoped value class that can hold a value of type T, while interfacing with a base class B. More...
class	PolytopeSet
	A convex polytope set in half-space representation. More...
class	RectSet
	Rectangular set over an arbitrary number of dimensions. More...
class	ScopedValueShield
	A utility class that temporarily shields all current scoped values of type T and Tags. More...
class	Set
	Generic set over a \( \texttip{d}{Dimension of the vector space} \) dimensional vector space \( \texttip{\mathcal{X}}{Polish sample vector space} \subseteq \mathbb{R}^d \). More...
class	SoplexOptimiser
	Linear optimiser using the SoPlex solver. More...
class	SphereSet
	Multidimensional sphere set. More...
struct	Stats
	Simple struct to hold various statistics about the execution of different components. More...
class	Tensor
	Lightweight tensor class. More...
class	TensorIterator
	Utility class to iterate over all elements of a tensor. More...
class	TensorView
	Lightweight wrapper that provides a view of a tensor. More...
class	Timer
	Timer class using the steady clock (wall time). More...
class	TimerBase
	Simple timer class to evaluate the performance of the software. More...
class	TimerGuard
	The TimeGuard wraps a timer object and pauses it when the guard object is destructed. More...
class	TruncatedFourierFeatureMap
	Truncated Fourier feature map. More...
class	Tuner
	Optimise the kernel hyperparameters. More...
struct	user_clock
	Structure that will hold the user clock data. More...
class	UserTimer
	Timer class using the user_clock (CPU user timer). More...
class	ValleePoussinKernel
	Vallée-Poussin kernel. More...

Concepts
concept	SizedDataContainer
	Check if the type T is a data container of type U having a data() method which returns a raw pointer and a size() method which returns the size of the container.
concept	MapFromTo
	Check if the type T constitutes a map from type From to type To.
concept	SelfReferenceCounter
	Check if the type T is a self-reference counter type.
concept	Iterable
	Check if the type T is an iterable type.
concept	SizedIterable
	Check if the type T is an iterable type with a size() method.
concept	TypedIterable
	Check if the type T is an iterable type with elements of type U.
concept	SizedTypedIterable
	Check if the type T is an iterable type with elements of type U and a size() method.
concept	IsAnyOf
	Check if the type T is any of the types U.
concept	IsNotAnyOf
	Check if the type T is not any of the types U.
concept	Arithmetic
	Check if the type T supports the arithmetic operations +, -, *, /.
concept	Numeric
	Check if the type T supports the arithmetic operations +, -, *, / and the comparison operators <, >, <=, >=.

Typedefs
using	OutputComputer = std::function<ConstMatrixRefCopy(const Estimator&, ConstMatrixRef)>
	Instead of providing the outputs directly to the estimator, this function can be used to compute them on the fly.
using	RadialBasisFunction = GaussianKernel
	Alias for Gaussian kernel.
using	SquaredExponentialKernel = GaussianKernel
	Alias for Gaussian kernel.
using	HP = Parameter
	Alias for HyperParameter.
using	Parameters = std::underlying_type_t<Parameter>
	Efficient set of parameters as bitset.
using	Requests = std::underlying_type_t<Request>
	Efficient set of requests.
template<class T, class... Tags>
using	ScopedValue = PolymorphicScopedValue<T, T, Tags...>
	Simplified scoped value class that holds a value of type T.

Enumerations
enum class	Parameter : std::uint16_t {   _ = 0 , SIGMA_F = 1 << 0 , SIGMA_L = 1 << 1 , REGULARIZATION_CONSTANT = 1 << 2 ,   DEGREE = 1 << 3 , GRADIENT_OPTIMIZABLE = 1 << 4 , A = 1 << 5 , B = 1 << 6 }
	List of available parameters used parametrizable objects (e.g., Estimator and Kernel). More...
enum class	Request : std::uint16_t { _ = 0 , OBJECTIVE_VALUE = 1 << 0 , GRADIENT = 1 << 1 }
	List of available requests a tuner can make to an Estimator and, by extension, to a Kernel. More...

Functions
Vector	peaks (const Vector &x, const Vector &y)
	Peaks function defined over a pair of vectors.
Matrix	peaks (const Matrix &x, const Matrix &y)
	Peaks function defined over a pair of meshgrids.
Matrix	mvnrnd (const Vector &mu, const Matrix &sigma)
	The multivariate normal distribution is a generalization of the univariate normal distribution to two or more variables.
Matrix	combvec (ConstMatrixRef m)
	Given a matrix m treat each row vector as a separate matrix and return their combination using combvec.
Scalar	rms (ConstMatrixRef x)
	Calculate the root mean square of the elements of a vector.
Vector	normal_cdf (ConstVectorRef x, Scalar sigma_f, Scalar sigma_l)
	Compute the Cumulative distribution function (CDF) of the normal distribution at oll point listed in \( \texttip{x}{Element of the vector space} \).
void	meshgrid (const Vector &x, const Vector &y, Matrix &X, Matrix &Y)
	Create a 2D grid coordinates based on the coordinates contained in vectors x and y.
void	meshgrid (const Vector &x, Matrix &X, Matrix &Y)
	Create a 2D grid coordinates based on the coordinates contained in vector x.
Vector	arange (const Scalar low, Scalar high, const Scalar step=1, const bool with_last=false)
	Create an evenly spaced values within a given interval.
Matrix	diff (ConstMatrixRef m, const int n=1, const bool rowwise=true)
	Calculates differences between adjacent elements of X n times.
template<class... Ms>
Matrix	combvec (ConstMatrixRef m1, ConstMatrixRef m2, const Ms &... matrices)
	Given \( m \) inputs matrices, where matrix \( M_i \) has \( n_i \) columns, return a matrix with \( \Pi_{i = 0}^m n_i \) column vectors, where the columns consist of all combinations found by combining one column vector from each input matrix.
Scalar	median (Matrix x)
	Compute the median of a vector or matrix.
template<Dimension P = 2, bool Squared = false, bool TriangularMatrix = false, class Derived> requires (P > 0) && (!Squared || P == 2)
auto	pdist (const Eigen::MatrixBase< Derived > &x)
	Compute the p-norm distance between every pair of row vectors in the input.
template<Dimension P = 2, bool Squared = false, class DerivedX, class DerivedY> requires (P > 0) && (!Squared || P == 2)
Matrix	pdist (const Eigen::MatrixBase< DerivedX > &x, const Eigen::MatrixBase< DerivedY > &y)
	Compute the p-norm distance between every pair of row vectors in the input matrices.
Eigen::MatrixXcd	fft2 (const Matrix &x)
	Perform a 2D Fast Fourier Transform (FFT) on the input matrix.
Matrix	ifft2 (const Eigen::MatrixXcd &x)
	Perform a 2D inverse Fast Fourier Transform (FFT) on the input matrix.
template<class Scalar>
Eigen::MatrixX< Scalar >	read_matrix (const std::string_view file_name)
	Read a matrix from a file.
template<class ArgType>
internal::CirculantOp< ArgType >	circulant (const Eigen::MatrixBase< ArgType > &arg)
	Create a circulant matrix from a vector arg.
template<class ArgType>
internal::ShiftOp< ArgType >	shift (const Eigen::MatrixBase< ArgType > &x, const Eigen::Index shift_rows, const Eigen::Index shift_cols)
	Shift the rows and columns of a matrix or vector x by shift_rows and shift_cols respectively.
template<class ArgType>
internal::ShiftOp< ArgType >	fftshift (const Eigen::MatrixBase< ArgType > &x)
	Rearrange a Fourier transform x by shifting the zero-frequency component to the center of the array.
template<class ArgType>
internal::ShiftOp< ArgType >	ifftshift (const Eigen::MatrixBase< ArgType > &x)
	Rearranges a zero-frequency-shifted Fourier transform x back to the original transform output.
template<class ArgType>
internal::PadtOp< ArgType >	pad (const Eigen::MatrixBase< ArgType > &x, const Eigen::Index pad_top, const Eigen::Index pad_bottom, const Eigen::Index pad_left, const Eigen::Index pad_right, const typename ArgType::Scalar &value)
	Pad a matrix or vector x with pad_top, pad_bottom, pad_left, and pad_right rows and columns respectively.
template<class ArgType>
internal::PadtOp< ArgType >	pad (const Eigen::MatrixBase< ArgType > &x, const Eigen::Index pad_size, const typename ArgType::Scalar &value)
	Pad a matrix or vector x with pad_size rows and columns in all directions, effectively adding 2 * pad_size rows and columns to the input.
template<class ArgType>
internal::PadtOp< ArgType >	pad (const Eigen::MatrixBase< ArgType > &x, const Eigen::Index pad_rows, const Eigen::Index pad_cols, const typename ArgType::Scalar &value)
	Pad a matrix or vector x with pad_rows rows and pad_cols columns in both directions, effectively adding 2 * pad_rows rows and 2 * pad_cols columns to the input.
template<class Derived>
Matrix	operator* (const MatrixBase< Derived > &A, const GramMatrix &gram_matrix)
	Left multiply the Gram matrix with another matrix, \( AK \).
double	compute_log_marginal (const GramMatrix &K, ConstMatrixRef y)
	Compute the log marginal likelihood of the model given the Gram matrix K and the training outputs y.
Vector	compute_log_marginal_gradient (const GramMatrix &K, const Matrix &alpha, const std::vector< Matrix > &gradient)
	Compute the gradient of the log marginal likelihood of the model given the Gram matrix K, the training outputs y, the coefficients alpha and the gradient of the Gram matrix with respect to the GRADIENT_OPTIMIZABLE hyperparameters.
template<class R, Parameter P>
R	dispatch (const std::function< R()> &fun_int, const std::function< R()> &fun_double, const std::function< R()> &fun_vector)
	Dispatch the correct function call depending on type associated with the parameter.
template<class R>
R	dispatch (const Parameter parameter, const std::function< R()> &fun_int, const std::function< R()> &fun_double, const std::function< R()> &fun_vector)
	Dispatch the correct function call depending on type associated with the parameter.
double	peaks (const double x, const double y)
	Peaks function defined over a pair of values.
double	normal_cdf (const double x, const double sigma_f, const double sigma_l)
	Compute the Cumulative distribution function (CDF) of the normal distribution at the point x.
template<class T> requires (std::is_integral_v<T>)
T	pow (T base, T exp)
	Raise a base to the power of an exponent: \( b^e \).

Variables
constexpr Parameters	NoParameters = static_cast<Parameters>(Parameter::_)
	No parameter value placeholder.
constexpr Requests	NoRequests = static_cast<Requests>(Request::_)
	No request value.

Detailed Description

Root namespace for the lucid library.

Typedef Documentation

OutputComputer

using lucid::OutputComputer = std::function<ConstMatrixRefCopy(const Estimator&, ConstMatrixRef)>

Instead of providing the outputs directly to the estimator, this function can be used to compute them on the fly.

Useful when the outputs are not available at the time of fitting/scoring, or depend on changing parameters.

Parameters

estimator	Estimator object involved in the computation
inputs	\( n \times d_x \) matrix of row vectors in the input space \( \mathcal{X} \)

Returns

\( n \times d_y \) matrix of row vectors in the output space \( \mathcal{Y} \)

ScopedValue

template<class T, class... Tags>

using lucid::ScopedValue = PolymorphicScopedValue<T, T, Tags...>

Simplified scoped value class that holds a value of type T.

This class is a specialization of PolymorphicScopedValue where T and B are the same type. It maintains a stack of instances, allowing access to the most recently created (top) and the first created (bottom) instances.

Template Parameters

T	Type of the value to be scoped.
Tags	Variadic template parameters to uniquely identify different scoped value types.

Enumeration Type Documentation

Parameter

enum class lucid::Parameter : std::uint16_t

strong

List of available parameters used parametrizable objects (e.g., Estimator and Kernel).

To check whether an object supports a specific parameter, use the has(Parameter) method. This enum behaves as a bitset. It is possible to combine multiple parameters using bitwise OR operations or to check if a parameter is set using the AND operations.

Parameter::_ // Empty set {}
Parameters u = Parameter::SIGMA_F | Parameter::SIGMA_L  // {SIGMA_F} U {SIGMA_L} = {SIGMA_F, SIGMA_L}
u | Parameter::DEGREE  // {SIGMA_F, SIGMA_L} U {DEGREE} = {SIGMA_F, SIGMA_L, DEGREE}
u & Parameter::SIGMA_F  // Set intersection {SIGMA_F, SIGMA_L} ∩ {SIGMA_F} = {SIGMA_F}
u && Parameter::SIGMA_F  // Check if {SIGMA_F, SIGMA_L} ∩ {SIGMA_F} = {SIGMA_F} is non-empty
u || Parameter::SIGMA_F  // Check if {SIGMA_F, SIGMA_L} ∪ {SIGMA_F} = {SIGMA_F, SIGMA_L} is non-empty

Note

The numerical values are offset in such a way that operating over them is very efficient.

Enumerator
_	No parameters. Used as the empty set placeholder.
SIGMA_F	Sigma_f parameter.
SIGMA_L	Sigma_l parameter.
REGULARIZATION_CONSTANT	Regularization constant parameter.
DEGREE	Degree of the polynomial.
GRADIENT_OPTIMIZABLE	Gradient optimizable parameter.
A	'a' parameter
B	'b' parameter

Request

enum class lucid::Request : std::uint16_t

strong

List of available requests a tuner can make to an Estimator and, by extension, to a Kernel.

If the request is not supported by the Estimator, nothing will happen. This enum behaves as a bitset. It is possible to combine multiple requests using bitwise OR operations or to check if a request is set using the AND operations.

Request::_ // Empty set {}
Requests u = Request::GRADIENT | Request::STATS  // {GRADIENT} U {STATS} = {STATS, GRADIENT}
u | Request::STATS  // {STATS, GRADIENT} U {DEGREE} = {STATS, GRADIENT}
u & Request::STATS  // Set intersection {STATS, GRADIENT} ∩ {STATS} = {STATS}
u && Request::STATS  // Check if {STATS, GRADIENT} ∩ {STATS} = {STATS} is non-empty
u || Request::STATS  // Check if {STATS, GRADIENT} ∪ {STATS} = {STATS, GRADIENT} is non-empty

Note

The values are offset in such a way that operating over them is very efficient.

Enumerator
_	No requests. Used as the empty set placeholder.
OBJECTIVE_VALUE	Compute the objective value of the Estimator.
GRADIENT	Compute the gradient of the objective value with respect to the Requests.

Function Documentation

arange()

Vector lucid::arange ( const Scalar low, Scalar high, const Scalar step = 1, const bool with_last = false )

inline

Create an evenly spaced values within a given interval.

Parameters

low	start of interval. The interval includes this value
high	end of interval. The interval does not include this value, unless with_last is true
step	spacing between values
with_last	whether to include the last value in the interval

Returns

vector of evenly spaced values

See also

https://numpy.org/doc/stable/reference/generated/numpy.arange.html

circulant()

template<class ArgType>

internal::CirculantOp< ArgType > lucid::circulant

(

const Eigen::MatrixBase< ArgType > &

arg

)

Create a circulant matrix from a vector arg.

A circulant matrix is a square matrix where each row is a right cyclic shift of the previous row.

Template Parameters

ArgType

type of the vector

Parameters

arg

vector

Returns

circulant matrix

combvec() [1/2]

Matrix lucid::combvec

(

ConstMatrixRef

m

)

Given a matrix m treat each row vector as a separate matrix and return their combination using combvec.

Parameters

m

matrix

Returns

matrix with all combinations of column vectors

See also

https://www.mathworks.com/help/deeplearning/ref/combvec.html

combvec() [2/2]

template<class... Ms>

Matrix lucid::combvec	(	ConstMatrixRef	m1,
		ConstMatrixRef	m2,
		const Ms &...	matrices )

Given \( m \) inputs matrices, where matrix \( M_i \) has \( n_i \) columns, return a matrix with \( \Pi_{i = 0}^m n_i \) column vectors, where the columns consist of all combinations found by combining one column vector from each input matrix.

Parameters

m1	first matrix
m2	second matrix
matrices	remaining matrices

Returns

matrix with all combinations of column vectors

See also

https://www.mathworks.com/help/deeplearning/ref/combvec.html

compute_log_marginal()

double lucid::compute_log_marginal	(	const GramMatrix &	K,
		ConstMatrixRef	y )

Compute the log marginal likelihood of the model given the Gram matrix K and the training outputs y.

The log marginal likelihood is given by:

\[\log P(y|x, \theta) = -\frac{1}{2}\ln|K| - \frac{1}{2}y^tK^{-1}y - \frac{N}{2}\ln{2\pi} . \]

where \( N \) is the number of training samples, \( K \) is the Gram matrix, \( \theta \) are the log hyperparameters of the kernel, \( y \) are the training outputs.

Parameters

K	Gram matrix
y	training outputs

Returns

log marginal likelihood

compute_log_marginal_gradient()

Vector lucid::compute_log_marginal_gradient	(	const GramMatrix &	K,
		const Matrix &	alpha,
		const std::vector< Matrix > &	gradient )

Compute the gradient of the log marginal likelihood of the model given the Gram matrix K, the training outputs y, the coefficients alpha and the gradient of the Gram matrix with respect to the GRADIENT_OPTIMIZABLE hyperparameters.

The gradient of the log marginal likelihood is given by:

\[\frac{\partial}{\partial\theta_i} \log P(y|x, \theta) = \frac{1}{2}y^TK^{-1}\frac{\partial K}{\partial\theta_i}K^{-1}y^T -\frac{1}{2}\mathrm{tr}\left(K^{-1}\frac{\partial K}{\partial\theta_i}\right) , \]

where \( N \) is the number of training samples, \( K \) is the Gram matrix, \( \theta \) are the log hyperparameters of the kernel, \( y \) are the training outputs. For efficiency reasons, we compute the coefficients \( \alpha = K^{-1}y \) beforehand and use them to rewrite the gradient as:

\[\frac{1}{2}\mathrm{tr}\left((\alpha\alpha^T - K^{-1})\frac{\partial K}{\partial\theta_i}\right) . \]

Note

The gradient is computed with respect to the log of the actual hyperparameters.

Parameters

K	Gram matrix
alpha	coefficients such that \( \alpha = K^{-1}y \)
gradient	gradient of the Gram matrix with respect to the GRADIENT_OPTIMIZABLE hyperparameters

Returns

log marginal likelihood function gradient with respect to the GRADIENT_OPTIMIZABLE hyperparameters

diff()

Matrix lucid::diff ( ConstMatrixRef m, const int n = 1, const bool rowwise = true )

inline

Calculates differences between adjacent elements of X n times.

By default, diff operates along the rows of X.

Parameters

m	matrix
n	number of differences
rowwise	whether to calculate differences along the rows or columns

Returns

matrix of differences

See also

https://www.mathworks.com/help/matlab/ref/double.diff.html

dispatch() [1/2]

template<class R>

R lucid::dispatch	(	const Parameter	parameter,
		const std::function< R()> &	fun_int,
		const std::function< R()> &	fun_double,
		const std::function< R()> &	fun_vector )

Dispatch the correct function call depending on type associated with the parameter.

Template Parameters

R	return type, the same for all the functions

Parameters

parameter	the parameter determining which function to dispatch
fun_int	function called if the parameter is integer valued
fun_double	function called if the parameter is double valued
fun_vector	function called if the parameter is vector valued

Returns

value returned by the function that ended up being called

dispatch() [2/2]

template<class R, Parameter P>

R lucid::dispatch	(	const std::function< R()> &	fun_int,
		const std::function< R()> &	fun_double,
		const std::function< R()> &	fun_vector )

Dispatch the correct function call depending on type associated with the parameter.

Template Parameters

R	return type, the same for all the functions
P	parameter determining which function to dispatch

Parameters

fun_int	function called if the parameter is integer valued
fun_double	function called if the parameter is double valued
fun_vector	function called if the parameter is vector valued

Returns

value returned by the function that ended up being called

fft2()

Eigen::MatrixXcd lucid::fft2 ( const Matrix & x )

inline

Perform a 2D Fast Fourier Transform (FFT) on the input matrix.

Parameters

x	input matrix

Returns

FFT of the input matrix

fftshift()

template<class ArgType>

internal::ShiftOp< ArgType > lucid::fftshift

(

const Eigen::MatrixBase< ArgType > &

x

)

Rearrange a Fourier transform x by shifting the zero-frequency component to the center of the array.

It is useful for visualizing the Fourier transform with the zero-frequency component in the center. Undoes the result of ifftshift.

• If x is a vector, then fftshift swaps the left and right halves of x.
• If x is a matrix, then fftshift swaps the first quadrant of x with the third, and the second quadrant with the fourth.

Template Parameters

ArgType

type of the matrix or vector

Parameters

x	matrix or vector

Returns

shifted matrix or vector

See also

https://www.mathworks.com/help/matlab/ref/fftshift.html

ifft2()

Matrix lucid::ifft2 ( const Eigen::MatrixXcd & x )

inline

Perform a 2D inverse Fast Fourier Transform (FFT) on the input matrix.

Parameters

x	input matrix

Returns

inverse FFT of the input matrix

ifftshift()

template<class ArgType>

internal::ShiftOp< ArgType > lucid::ifftshift

(

const Eigen::MatrixBase< ArgType > &

x

)

Rearranges a zero-frequency-shifted Fourier transform x back to the original transform output.

Undoes the result of fftshift.

• If x is a vector, then ifftshift swaps the left and right halves of x.
• If x is a matrix, then ifftshift swaps the first quadrant of x with the third, and the second quadrant with the fourth.

Template Parameters

ArgType

type of the matrix or vector

Parameters

x	matrix or vector

Returns

shifted matrix or vector

See also

https://www.mathworks.com/help/matlab/ref/ifftshift.html

median()

Scalar lucid::median ( Matrix x )

inline

Compute the median of a vector or matrix.

If the vector has an even number of elements, the median is the mean of the two middle elements.

Warning

The storage order of the matrix matters, while it changes nothing for vectors.

Parameters

x	vector or matrix

Returns

median of the vector or matrix

See also

https://stackoverflow.com/a/62698308/15153171

meshgrid() [1/2]

void lucid::meshgrid ( const Vector & x, const Vector & y, Matrix & X, Matrix & Y )

inline

Create a 2D grid coordinates based on the coordinates contained in vectors x and y.

X is a matrix where each row is a copy of x and Y is a matrix where each column is a copy of y. The grid represented by the coordinates X and Y has y.size() rows and x.size() columns.

Parameters

	x	x coordinates
	y	y coordinates
[out]	X	x coordinates grid
[out]	Y	y coordinates grid

See also

https://www.mathworks.com/help/matlab/ref/meshgrid.html

meshgrid() [2/2]

void lucid::meshgrid ( const Vector & x, Matrix & X, Matrix & Y )

inline

Create a 2D grid coordinates based on the coordinates contained in vector x.

Equivalent to calling meshgrid with as meshgrid(x, x, X, Y).

Parameters

	x	x coordinates
[out]	X	x coordinates grid
[out]	Y	y coordinates grid

See also

https://www.mathworks.com/help/matlab/ref/meshgrid.html

mvnrnd()

Matrix lucid::mvnrnd	(	const Vector &	mu,
		const Matrix &	sigma )

The multivariate normal distribution is a generalization of the univariate normal distribution to two or more variables.

It has two parameters, a mean vector \( \) \mu \( \) and a covariance matrix \( \Sigma \), that are analogous to the mean and variance parameters of a univariate normal distribution. The diagonal elements of \( \Sigma \) contain the variances for each variable, and the off-diagonal elements of \( \Sigma \) contain the covariances between variables. The probability density function (pdf) of the d-dimensional multivariate normal distribution is

\[ f(x | \mu, \Sigma) = \frac{1}{(2\pi)^{d/2}|\Sigma|^{1/2}} \exp\left(-\frac{1}{2}(x - \mu)^T\Sigma^{-1}(x - \mu)\right) \]

Although the multivariate normal cdf does not have a closed form, mvncdf can compute cdf values numerically.

Note

The seed for the random number generator can be set using random::seed.

Parameters

mu	mean vector
sigma	covariance matrix

Returns

random samples from the multivariate normal distribution

See also

https://www.mathworks.com/help/stats/mvnrnd.html

normal_cdf() [1/2]

double lucid::normal_cdf ( const double x, const double sigma_f, const double sigma_l )

inline

Compute the Cumulative distribution function (CDF) of the normal distribution at the point x.

Parameters

x	point at which to compute the CDF
sigma_f	\( \sigma_f \) value used in the normal distribution (mean)
sigma_l	\( \sigma_l \) value used in the normal distribution (standard deviation)

Returns

value of the CDF at the given point

normal_cdf() [2/2]

Vector lucid::normal_cdf	(	ConstVectorRef	x,
		Scalar	sigma_f,
		Scalar	sigma_l )

Compute the Cumulative distribution function (CDF) of the normal distribution at oll point listed in \( \texttip{x}{Element of the vector space} \).

Parameters

x	points at which to evaluate the CDF
sigma_f	\( \sigma_f \) value used in the normal distribution (mean)
sigma_l	\( \sigma_l \) value used in the normal distribution (standard deviation)

Returns

vector of CDF values at each point in \( \texttip{x}{Element of the vector space} \)

operator*()

template<class Derived>

Matrix lucid::operator*	(	const MatrixBase< Derived > &	A,
		const GramMatrix &	gram_matrix )

Left multiply the Gram matrix with another matrix, \( AK \).

Template Parameters

Derived

type of the other matrix

Parameters

A	matrix to multiply with the Gram matrix
gram_matrix	Gram matrix to multiply with

Returns

result of the multiplication

pad() [1/3]

template<class ArgType>

internal::PadtOp< ArgType > lucid::pad	(	const Eigen::MatrixBase< ArgType > &	x,
		const Eigen::Index	pad_rows,
		const Eigen::Index	pad_cols,
		const typename ArgType::Scalar &	value )

Pad a matrix or vector x with pad_rows rows and pad_cols columns in both directions, effectively adding 2 * pad_rows rows and 2 * pad_cols columns to the input.

The padding value is set to value.

Template Parameters

ArgType

type of the matrix or vector

Parameters

x	matrix or vector
pad_rows	padding rows to be added in both directions
pad_cols	padding columns to be added in both directions
value	padding value

Returns

padded matrix or vector

pad() [2/3]

template<class ArgType>

internal::PadtOp< ArgType > lucid::pad	(	const Eigen::MatrixBase< ArgType > &	x,
		const Eigen::Index	pad_size,
		const typename ArgType::Scalar &	value )

Pad a matrix or vector x with pad_size rows and columns in all directions, effectively adding 2 * pad_size rows and columns to the input.

The padding value is set to value.

Template Parameters

ArgType

type of the matrix or vector

Parameters

x	matrix or vector
pad_size	padding rows and columns to be added in all directions,
value	padding value

Returns

padded matrix or vector

pad() [3/3]

template<class ArgType>

internal::PadtOp< ArgType > lucid::pad	(	const Eigen::MatrixBase< ArgType > &	x,
		const Eigen::Index	pad_top,
		const Eigen::Index	pad_bottom,
		const Eigen::Index	pad_left,
		const Eigen::Index	pad_right,
		const typename ArgType::Scalar &	value )

Pad a matrix or vector x with pad_top, pad_bottom, pad_left, and pad_right rows and columns respectively.

The padding value is set to value.

Template Parameters

ArgType

type of the matrix or vector

Parameters

x	matrix or vector
pad_top	padding rows at the top
pad_bottom	padding rows at the bottom
pad_left	padding columns at the left
pad_right	padding columns at the right
value	padding value

Returns

padded matrix or vector

pdist() [1/2]

template<Dimension P = 2, bool Squared = false, bool TriangularMatrix = false, class Derived>
requires (P > 0) && (!Squared || P == 2)

auto lucid::pdist

(

const Eigen::MatrixBase< Derived > &

x

)

Compute the p-norm distance between every pair of row vectors in the input.

If the input has shape \( N \times M \) the output vector will contain \( \frac{1}{2}N(N-1) \) elements or be a lower triangular matrix, depending on TriangularMatrix.

\[\text{{input}} = \begin{bmatrix} x_1 \\ x_2 \\ \vdots \\ x_N \end{bmatrix} \]

Todo

Remove TriangularMatrix tparam in favor of squareform function

Template Parameters

P	norm order
Squared	whether to compute the squared distance. Only available for p == 2
TriangularMatrix	whetehr to return a lower triangular matrix with all the distances or a vector view of the strictly lower section of the full matrix

Parameters

x	input matrix

Returns

vector of distances or lower triangular matrix.

pdist() [2/2]

template<Dimension P = 2, bool Squared = false, class DerivedX, class DerivedY>
requires (P > 0) && (!Squared || P == 2)

Matrix lucid::pdist	(	const Eigen::MatrixBase< DerivedX > &	x,
		const Eigen::MatrixBase< DerivedY > &	y )

Compute the p-norm distance between every pair of row vectors in the input matrices.

Template Parameters

DerivedX	type of the first input matrix
DerivedY	type of the second input matrix
P	norm order
Squared	whether to compute the squared distance. Only available for p == 2

Parameters

x	input matrix
y	input matrix

Returns

matrix of distances

peaks() [1/3]

double lucid::peaks ( const double x, const double y )

inline

Peaks function defined over a pair of values.

Useful for demonstrating graphics functions, such as contour, mesh, pcolor, and surf. It is obtained by translating and scaling Gaussian distributions and is defined as

\[f(x, y) = 3(1 - x)^2 \exp(-x^2 - (y + 1)^2) - 10\left(\frac{x}{5} - x^3 - y^5\right) \exp(-x^2 - y^2) - \frac{1}{3} \exp(-(x + 1)^2 - y^2) \]

Parameters

x	x value
y	y value

Returns

value of the peaks function at the given point

peaks() [2/3]

Matrix lucid::peaks	(	const Matrix &	x,
		const Matrix &	y )

Peaks function defined over a pair of meshgrids.

Useful for demonstrating graphics functions, such as contour, mesh, pcolor, and surf. It is obtained by translating and scaling Gaussian distributions and is defined as

\[f(x, y) = 3(1 - x)^2 \exp(-x^2 - (y + 1)^2) - 10\left(\frac{x}{5} - x^3 - y^5\right) \exp(-x^2 - y^2) - \frac{1}{3} \exp(-(x + 1)^2 - y^2) \]

The function will be computed element-wise, producing a grid of the same size as the input grids.

Parameters

x	2D grid of x values
y	2D grid of y values

Returns

2D grid obtained by the application of the peaks function component-wise over the two input grids

See also

https://www.mathworks.com/help/matlab/ref/peaks.html

peaks() [3/3]

Vector lucid::peaks	(	const Vector &	x,
		const Vector &	y )

Peaks function defined over a pair of vectors.

Useful for demonstrating graphics functions, such as contour, mesh, pcolor, and surf. It is obtained by translating and scaling Gaussian distributions and is defined as

\[f(x, y) = 3(1 - x)^2 \exp(-x^2 - (y + 1)^2) - 10\left(\frac{x}{5} - x^3 - y^5\right) \exp(-x^2 - y^2) - \frac{1}{3} \exp(-(x + 1)^2 - y^2) \]

The function will be computed element-wise, producing a vector of the same size as the input vectors.

Parameters

x	vector of x values
y	vector of y values

Returns

vector obtained by the application of the peaks function component-wise over the two input vectors

See also

https://www.mathworks.com/help/matlab/ref/peaks.html

pow()

template<class T>
requires (std::is_integral_v<T>)

T lucid::pow ( T base, T exp )

inline

Raise a base to the power of an exponent: \( b^e \).

Template Parameters

T	type of base and exponent. Must be an integral type.

Parameters

base	\( b \) base
exp	\( e \) exponent

Returns

base raised to the power of exp

read_matrix()

template<class Scalar>

Eigen::MatrixX< Scalar > lucid::read_matrix

(

const std::string_view

file_name

)

Read a matrix from a file.

The file must have the following format:

rowsXcols
element_1,element_2,...,element_n

Template Parameters

Scalar

type of the matrix

Parameters

file_name

name of the file to read

Returns

matrix read from the file

rms()

Scalar lucid::rms

(

ConstMatrixRef

x

)

Calculate the root mean square of the elements of a vector.

Parameters

x

vector

Returns

root mean square

shift()

template<class ArgType>

internal::ShiftOp< ArgType > lucid::shift	(	const Eigen::MatrixBase< ArgType > &	x,
		const Eigen::Index	shift_rows,
		const Eigen::Index	shift_cols )

Shift the rows and columns of a matrix or vector x by shift_rows and shift_cols respectively.

The sign of the shift determines the direction of the shift. Overflows are wrapped around.

Template Parameters

ArgType

type of the matrix or vector

Parameters

x	matrix or vector
shift_rows	shift rows. If negative, the rows are shifted up.
shift_cols	shift columns. If negative, the columns are shifted left.

Returns

shifted matrix or vector