API

Core Functions

laplace_reconstruct(laplace_rep_func, p, t)

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations.

laplace_reconstruct

torchlaplace.laplace_reconstruct(laplace_rep_func, p, t, recon_dim=None, ilt_algorithm='fourier', use_sphere_projection=True, ilt_reconstruction_terms=33, options=None, compute_deriv=False, x0=None) → torch.Tensor

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations.

Given a parameterized Laplace representation functional \(\mathbf{F}(\mathbf{p},\mathbf{s})\),

\[\begin{aligned} \mathbf{x}(t) & = \text{inverse_laplace_transform}(\mathbf{F}(\mathbf{p},\mathbf{s}), t) \end{aligned}\]

Where \(\mathbf{p}\) is a Tensor encoding the initial system state as a latent variable, and \(t\) is the time points to reconstruct trajectories for.

The parameterized Laplace representation functional laplace_rep_func, \(\mathbf{F}(\mathbf{p},\mathbf{s})\) also takes an input complex value \(\mathbf{s}\). This \(\mathbf{s}\) is used internally when reconstructing a specified time point with the selected inverse Laplace transform algorithm ilt_algorithm.

Output dtypes and numerical precision are based on the dtypes of the inputs p.

The reconstructions \(\mathbf{x}(t)\) are of shape \((\text{MiniBatchSize}, \text{SeqLen}, d_{\text{obs}})\). Where \(\text{SeqLen}\) dimension corresponds to the input evaluated time points \(t\), and \(d_{\text{obs}}\) is the trajectory dimension for a given time point, \(\mathbf{x}(t)\).

Parameters

  • laplace_rep_func (nn.Module) – Function that maps an input of two tensors, first a scalar Tensor p encoding the initial system state and secondly a complex Tensor s used to evaluate the Laplace representation.

  • p (Tensor) – latent variable Tensor of shape \((\text{MiniBatchSize}, \text{K})\). Where \(\text{K}\) is a hyperparameter, and can be set by the user to their desired value.

  • t (Tensor) – time points to reconstruct trajectories for of shape \((\text{MiniBatchSize}, \text{SeqLen})\) or \((\text{SeqLen})\) if all trajectories use the same time points.

  • recon_dim (int) – trajectory dimension for a given time point. Corresponds to dim \(d_{\text{obs}}\). If not explicitly specified, will use the same last dimension of p, i.e. \(\text{K}\).

  • ilt_algorithm (str) – inverse Laplace transform algorithm to use. Default: fourier. Available are {fourier, dehoog, cme, fixed_tablot, stehfest}. See inverse_laplace.py for further details.

  • use_sphere_projection (bool) – this uses the laplace_rep_func in the stereographic projection of the Riemann sphere. Default True.

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in laplace_rep_func to reconstruct a single time point.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{MiniBatchSize}, \text{SeqLen}, d_{\text{obs}})\) or if no mini batch of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

Raises

ValueError – if an invalid ilt_algorithm is provided.

Inverse Laplace transform algorithms

Each Inverse Laplace transform algorithm is a class that has a unified API, of three default parameters of ilt_reconstruction_terms (int, default of 33), torch_float_datatype (default of torch.float32) and torch_complex_datatype (default of torch.cfloat). Note to use double precision use torch_float_datatype=torch.double and torch_complex_datatype=torch.cdouble.

InverseLaplaceTransformAlgorithmBase([...])

Base class for Inverse Laplace Transform (ILT) Algorithms.

Fourier([ilt_reconstruction_terms, alpha, ...])

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

DeHoog([ilt_reconstruction_terms, alpha, ...])

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

FixedTablot([ilt_reconstruction_terms, ...])

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

Stehfest([ilt_reconstruction_terms, ...])

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

CME([ilt_reconstruction_terms, ...])

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

InverseLaplaceTransformAlgorithmBase

class torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase(ilt_reconstruction_terms=33, torch_float_datatype=torch.float32, torch_complex_datatype=torch.complex64)

Base class for Inverse Laplace Transform (ILT) Algorithms. This reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations.

Given a parameterized Laplace representation function \(\mathbf{F}(\mathbf{s})\),

\[\begin{aligned} \mathbf{x}(t) & = \text{inverse_laplace_transform}(\mathbf{F}(\mathbf{s}), t) \end{aligned}\]

Where \(t\) is the time points to reconstruct trajectories for.

The Laplace representation function fs, \(\mathbf{F}(\mathbf{s})\) takes an input complex value \(\mathbf{s}\). This \(\mathbf{s}\) is used internally when reconstructing a specified time point with the selected inverse Laplace transform algorithm class.

The reconstructions \(\mathbf{x}(t)\) are of shape \((\text{MiniBatchSize}, \text{SeqLen}, d_{\text{obs}})\). Where \(\text{SeqLen}\) dimension corresponds to the input evaluated time points \(t\), and \(d_{\text{obs}}\) is the trajectory dimension for a given time point, \(\mathbf{x}(t)\).

The inverse Laplace transform (ILT) is defined as

\[\begin{aligned} \hat{\mathbf{x}}(t) = \mathcal{L}^{-1}\{\mathbf{F}(\mathbf{s})\}(t)=\frac{1}{2\pi i} \int_{\sigma - i \infty}^{\sigma + i \infty} \mathbf{F}(\mathbf{s})e^{\mathbf{s}t}d\mathbf{s} \end{aligned}\]

where the integral refers to the Bromwich contour integral in \(\mathbb{C}^d\) with the contour \(\sigma>0\) chosen such that all the singularities of \(\mathbf{F}(\mathbf{s})\) are to the left of it [1].

Many algorithms have been developed to numerically evaluate the ILT Equation (above). On a high level, they involve two steps:

\[\begin{split}\begin{aligned} \mathcal{Q}(t) &= \text{ILT-Query} (t) \\ \hat{\mathbf{x}}(t) &= \text{ILT-Compute}\big(\{\mathbf{F}(\mathbf{s})| \mathbf{s} \in \mathcal{Q}(t) \}\big) \end{aligned}\end{split}\]

To evaluate \(\mathbf{x}(t)\) on time points \(t \in \mathcal{T} \subset \mathbb{R}\), the algorithms first construct a set of query points \(\mathbf{s} \in \mathcal{Q}(\mathcal{T}) \subset \mathbb{C}\). They then compute \(\hat{\mathbf{x}}(t)\) using the \(\mathbf{F}(\mathbf{s})\) evaluated on these points. The number of query points scales linearly with the number of time points, i.e. \(|\mathcal{Q}(\mathcal{T})| = b |\mathcal{T}|\), where the constant \(b > 1\), denotes the number of reconstruction terms per time point and is specific to the algorithm. Importantly, the computation complexity of ILT only depends on the number of time points, but not their values (e.g. ILT for \(t=0\) and \(t=100\) requires the same amount of computation). The vast majority of ILT algorithms are differentiable with respect to \(\mathbf{F}(\mathbf{s})\), which allows the gradients to be back propagated through the ILT transform [1].

Parameters

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in fs to reconstruct a single time point.

  • torch_float_datatype (Torch.dtype) – Torch float datatype to use internally in the ILT algorithm, and also output data type of \(\mathbf{x}(t)\). Default torch.float32.

  • torch_complex_datatype (Torch.dtype) – Torch complex datatype to use internally in the ILT algorithm. Default torch.cfloat.

compute_s(ti)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at, from the input time points \(t\), using the selected ILT algorithm.

Parameters

ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{SeqLen}, \text{ReconTerms})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\).

forward(fs, ti)

Reconstructs a trajectory \(\mathbf{x}(t)\) for a Laplace representation \(\mathbf{F}(\mathbf{s})\), at time points \(t\).

Parameters

  • fs (Torch.nn.Module or Callable) – The first parameter.

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate(fp, ti)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_all_multi(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm (takes batch input of fp).

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Best practice for most ILT algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\).

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

Fourier

class torchlaplace.inverse_laplace.Fourier(ilt_reconstruction_terms=33, alpha=0.001, tol=None, scale=2.0, eps=1e-06, torch_float_datatype=torch.float32, torch_complex_datatype=torch.complex64)

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations. Given a parameterized Laplace representation function \(\mathbf{F}(\mathbf{s})\).

Expands ILT Equation into an expanded Fourier transform, approximating it with the trapezoidal rule. This keeps the Bromwich contour parallel to the imaginary axis, and shifts it along the real axis, i.e. \(\sigma \propto \frac{1}{t}\). It is fairly easy to implement and scale to multiple dimensions. We denote \(s=\sigma + i \omega\) and we can express it as,

\[\begin{split}\begin{split} \mathbf{x}(t) & = \frac{1}{\pi}e^{\sigma t} \int_0^\infty \Re \left\{ F(s) e^{i \omega t} \right\} d \omega \\ & \approx \frac{1}{T} e^{\sigma t} \left[ \frac{F(\sigma)}{2} + \sum_{k=1}^{2N} \Re \left\{ F \left( \sigma + \frac{ik\pi}{T} \right)e^{\frac{ik \pi t}{T}} \right\} \right] \end{split}\end{split}\]

Where we approximate the first Fourier ILT, Equation as a discretized version, using the trapezoidal rule with step size \(\frac{\pi}{T}\) and evaluating \(s\) at the approximation points \(s_k=\sigma + \frac{ik\pi}{T}\) in the trapezoidal summation. We set the parameters of \(\sigma=\alpha-\frac{\log(\epsilon)}{T}\), with \(\alpha=1e-3\), \(\epsilon=10\alpha\), and the scaling parameter \(T=2t\). This gives the query function,

\[\begin{split}\begin{split} s_k(t) & = \text{1e-3} - \frac{\log(\text{1e-2})}{2t} + \frac{ik\pi}{2t} \\ \mathcal{Q}(t) & = [s_0(t), \ldots, s_{2N}(t)]^T \end{split}\end{split}\]

Where we model the equation with \(2N + 1\) reconstruction terms, setting \(N=16\) in experiments, and use double point floating precision to increase the numerical precision of the ILT.

The ILT-FSI equation provides guarantees that we can always find the inverse from time \(t: 0 \rightarrow \infty\), given that the singularities of the system (i.e. the points at which \(F(s) \to \infty\)) lie left of the contour of integration, and this puts no constraint on the imaginary frequency components we can model. Of course in practice, we often do not model time at \(\infty\) and instead model up to a fixed time in the future, which then bounds the exponentially increasing system trajectories, and their associated system poles that we can model \(\sigma \propto \frac{1}{t}\).

Parameters

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in fs to reconstruct a single time point.

  • torch_float_datatype (Torch.dtype) – Torch float datatype to use internally in the ILT algorithm, and also output data type of \(\mathbf{x}(t)\). Default torch.float32.

  • torch_complex_datatype (Torch.dtype) – Torch complex datatype to use internally in the ILT algorithm. Default torch.cfloat.

  • alpha (float) – \(\alpha\), default \(\alpha=1e-3\).

  • tol (float) – desired tolerance, if not specified simply related to alpha as \(\text{tol}=10\alpha\).

  • scale (float) – scaling factor (tuneable), default 2.0.

  • eps (float) – Small machine floating point precision, default \(\text{eps}=1e-6\).

compute_s(ti, time_max=None, Ti=None)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at, from the input time points \(t\), using the selected ILT algorithm.

Parameters

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

  • Ti (float) – Scaled maximum time to compute reconstruction up to. Best results use default of None, as this uses T=time_max * self.scale.

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{SeqLen}, \text{ReconTerms})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\).

forward(fs, ti, time_max=None, Ti=None)

Reconstructs a trajectory \(\mathbf{x}(t)\) for a Laplace representation \(\mathbf{F}(\mathbf{s})\), at time points \(t\).

Parameters

  • fs (Torch.nn.Module or Callable) – The first parameter.

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

  • Ti (float) – Scaled maximum time to compute reconstruction up to. Best results use default of None, as this uses T=time_max * self.scale.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (most ILT algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_all_multi(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm (takes batch input of fp).

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for most ILT algorithms is

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_all_multi_batch_time(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm (takes batch input of fp).

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (to set T =) – time points to reconstruct trajectory for of shape \((\text{BatchSize}, \text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for most ILT algorithms is

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_multi(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (most ILT algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

DeHoog

class torchlaplace.inverse_laplace.DeHoog(ilt_reconstruction_terms=33, alpha=1e-10, tol=None, scale=2.0, torch_float_datatype=torch.float32, torch_complex_datatype=torch.complex64)

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations. Given a parameterized Laplace representation function \(\mathbf{F}(\mathbf{s})\).

De Hoog Is an accelerated version of the Fouier ILT, defined in torchlaplace.inverse_laplace.Fourier(). It uses a non-linear double acceleration, using Padé approximation along with a remainder term for the series. This is somewhat complicated to implement, due to the recurrence operations to represent the Padé approximation, due to this although higher precision, the gradients have to propagate through many recurrence relation paths, making it slow to use in practice compared to Fourier (FSI), however more accurate when we can afford the additional time complexity.

Note

Reference: De Hoog, F. R., Knight, J., and Stokes, A. An improved method for numerical inversion of laplace transforms. SIAM Journal on Scientific and Statistical Computing, 3(3):357–366, 1982

Parameters

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in fs to reconstruct a single time point.

  • torch_float_datatype (Torch.dtype) – Torch float datatype to use internally in the ILT algorithm, and also output data type of \(\mathbf{x}(t)\). Default torch.float32.

  • torch_complex_datatype (Torch.dtype) – Torch complex datatype to use internally in the ILT algorithm. Default torch.cfloat.

  • alpha (float) – \(\alpha\), default \(\alpha=10e-10\).

  • tol (float) – desired tolerance, if not specified simply related to alpha as \(\text{tol}=10\alpha\).

  • scale (float) – scaling factor (tuneable), default 2.0.

compute_fixed_s(time_max)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at for a single input time point time_max, using the selected ILT algorithm.

Parameters

time_max (float) – Maximum time to compute reconstruction up to, a single time point to generate s for.

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{ReconTerms})\).

compute_s(ti, time_max=None, Ti=None)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at, from the input time points \(t\), using the selected ILT algorithm.

Parameters

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

  • Ti (float) – Scaled maximum time to compute reconstruction up to. Best results use default of None, as this uses T=time_max * self.scale.

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{SeqLen}, \text{ReconTerms})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\).

fixed_line_integrate(fp, ti, time_max)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for most ILT

  • ti –

  • T. (for the ILT algorithms that rely on) –

  • time_max (float) – Maximum time to compute reconstruction up to, a single time point to generate s for.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

forward(fs, ti, time_max=None, Ti=None)

Reconstructs a trajectory \(\mathbf{x}(t)\) for a Laplace representation \(\mathbf{F}(\mathbf{s})\), at time points \(t\).

Parameters

  • fs (Torch.nn.Module or Callable) – The first parameter.

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

  • Ti (float) – Scaled maximum time to compute reconstruction up to. Best results use default of None, as this uses T=time_max * self.scale.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for most ILT

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_all_multi(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm (takes batch input of fp).

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for most ILT

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

FixedTablot

class torchlaplace.inverse_laplace.FixedTablot(ilt_reconstruction_terms=33, torch_float_datatype=torch.float32, torch_complex_datatype=torch.complex64)

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations. Given a parameterized Laplace representation function \(\mathbf{F}(\mathbf{s})\).

Deforms the Bromwich contour around the negative real axis, where \(\mathbf{F}(\mathbf{s})\) must not overflow as \(\mathbf{s} \to -\infty\), and makes the Bromwich contour integral rapidly converge as \(\mathbf{s} \to -\infty\) causes \(e^{\mathbf{s}t} \to 0\) in ILT Equation. We implemented the Fixed Tablot method, which is simple to implement. However it suffers from not being able to model solutions that have large sinusoidal components and instead is optimized for modelling decaying exponential solutions. We note that whilst it can approximate some small sinusoidal components, for an adaptive time contour, the sinusoidal components that can be represented decrease when modelling longer time trajectories, and in the limit for long time horizons, allow only representations of decaying exponentials.

Note

References: Abate, J. and Valko, P. P. Multi-precision laplace transform inversion. International Journal for Numerical Methods in Engineering, 60:979–993, 2004.

Talbot, A. The accurate numerical inversion of laplace transforms. IMA Journal of Applied Mathematics, 23(1): 97–120, 1979.

Parameters

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in fs to reconstruct a single time point.

  • torch_float_datatype (Torch.dtype) – Torch float datatype to use internally in the ILT algorithm, and also output data type of \(\mathbf{x}(t)\). Default torch.float32.

  • torch_complex_datatype (Torch.dtype) – Torch complex datatype to use internally in the ILT algorithm. Default torch.cfloat.

compute_s(ti, time_max=None)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at, from the input time points \(t\), using the selected ILT algorithm.

Parameters

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{SeqLen}, \text{ReconTerms})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\).

forward(fs, ti, time_max=None)

Reconstructs a trajectory \(\mathbf{x}(t)\) for a Laplace representation \(\mathbf{F}(\mathbf{s})\), at time points \(t\).

Parameters

  • fs (Torch.nn.Module or Callable) – The first parameter.

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate(fp, ti, time_max=None)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_multi(fp, ti, time_max=None)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • time_max (float) – Maximum time to compute reconstruction up to. Best results use default of None, as this uses time_max=ti.

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

Stehfest

class torchlaplace.inverse_laplace.Stehfest(ilt_reconstruction_terms=33, torch_float_datatype=torch.float32, torch_complex_datatype=torch.complex64)

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations. Given a parameterized Laplace representation function \(\mathbf{F}(\mathbf{s})\).

Uses a discrete version of the Post-Widder formula that is an approximation for ILT Equation using a power series expansion of real part of \(\mathbf{s}\). It has internal terms that alternate in sign and become large as the order of approximation is increased, and suffers from numerical precision issues for large orders of approximation. It is fairly easy to implement.

Note

Reference: Al-Shuaibi, A. Inversion of the laplace transform via post—widder formula. Integral Transforms and Special Functions, 11(3):225–232, 2001.

Parameters

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in fs to reconstruct a single time point.

  • torch_float_datatype (Torch.dtype) – Torch float datatype to use internally in the ILT algorithm, and also output data type of \(\mathbf{x}(t)\). Default torch.float32.

  • torch_complex_datatype (Torch.dtype) – Torch complex datatype to use internally in the ILT algorithm. Default torch.cfloat.

compute_s(ti)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at, from the input time points \(t\), using the selected ILT algorithm.

Parameters

ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{SeqLen}, \text{ReconTerms})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\).

forward(fs, ti)

Reconstructs a trajectory \(\mathbf{x}(t)\) for a Laplace representation \(\mathbf{F}(\mathbf{s})\), at time points \(t\).

Parameters

  • fs (Torch.nn.Module or Callable) – The first parameter.

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate(fp, ti)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

CME

class torchlaplace.inverse_laplace.CME(ilt_reconstruction_terms=33, torch_float_datatype=torch.float32, torch_complex_datatype=torch.complex64)

Inherits from torchlaplace.inverse_laplace.InverseLaplaceTransformAlgorithmBase().

Reconstruct trajectories \(\mathbf{x}(t)\) for a system of Laplace representations. Given a parameterized Laplace representation function \(\mathbf{F}(\mathbf{s})\).

Concentrated matrix exponential (CME), uses a similar form to that of the Fourier Series Inverse, approximating ILT Equation with the trapezoidal rule. This uses the form of,

\[\begin{aligned} \mathbf{x}(t) \approx \frac{1}{T}\sum_{k=1}^{2N} \eta_k F \left(\frac{\beta_k}{T}\right) \end{aligned}\]

The coefficients \(\eta_k, \beta_k\) are determined by a complex procedure, with a numerical optimization step involved. This provides a good approximation for the reconstruction and the coefficients of up to a pre-specified order can be pre-computed and cached for low complexity run time. Similarly to Fourier (FSI), CMEs Bromwich contour remains parallel to the imaginary axis and is shifted along the real axis, i.e. \(\sigma \propto \frac{1}{t}\). It is moderately easy to implement when using pre-computed coefficients and scale to multiple dimensions.

Note

Reference: Horváth, G., Horváth, I., Almousa, S. A.-D., and Telek, M. Numerical inverse laplace transformation using concentrated matrix exponential distributions. Performance Evaluation, 137:102067, 2020.

Parameters

  • ilt_reconstruction_terms (int) – number of ILT reconstruction terms, i.e. the number of complex \(s\) points in fs to reconstruct a single time point.

  • torch_float_datatype (Torch.dtype) – Torch float datatype to use internally in the ILT algorithm, and also output data type of \(\mathbf{x}(t)\). Default torch.float32.

  • torch_complex_datatype (Torch.dtype) – Torch complex datatype to use internally in the ILT algorithm. Default torch.cfloat.

compute_s(ti)

Computes \(\mathbf{s}\) to evaluate the Laplace representation \(\mathbf{F}(\mathbf{s})\) at, from the input time points \(t\), using the selected ILT algorithm.

Parameters

ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of complex s points \(\mathbf{s}\) of shape \((\text{SeqLen}, \text{ReconTerms})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\).

forward(fs, ti)

Reconstructs a trajectory \(\mathbf{x}(t)\) for a Laplace representation \(\mathbf{F}(\mathbf{s})\), at time points \(t\).

Parameters

  • fs (Torch.nn.Module or Callable) – The first parameter.

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate(fp, ti)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm.

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Tensor) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_all_multi(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm (takes batch input of fp).

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (Best practice for most ILT algorithms is to set T =) – time points to reconstruct trajectory for of shape \((\text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\).

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

line_integrate_all_multi_batch_time(fp, ti, T)

Reconstruct trajectories \(\mathbf{x}(t)\) for fp, Laplace representations evaluated at s points from the input ti points, \(t\), using the selected ILT algorithm (takes batch input of fp).

Parameters

  • fp (Tensor) – Laplace representation evaluated at s points derived from the input time points ti. fp has shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}}, \text{ReconTerms})\)

  • ti (to set T =) – time points to reconstruct trajectory for of shape \((\text{BatchSize}, \text{SeqLen})\).

  • T (Tensor) – time points to reconstruct trajectory for used as the reconstruction of times up to T time point of shape \((\text{SeqLen})\). Best practice for most ILT algorithms is

  • ti –

  • T. (for the ILT algorithms that rely on) –

Returns

Tensor of reconstructions \(\mathbf{x}(t)\) of shape \((\text{BatchSize}, \text{SeqLen}, d_{\text{obs}})\). \(\text{SeqLen}\) dimension corresponds to the different time points \(t\). This tensor of reconstructions contains the solved value of \(\mathbf{x}\) for each desired time point in t.

Transformation Functions

complex_to_spherical_riemann(s_real, s_imag)

Complex coordinates to to Spherical Riemann stereographic projection coordinates.

spherical_riemann_to_complex(theta, phi)

Spherical Riemann stereographic projection coordinates to complex number coordinates.

spherical_to_complex(theta, phi)

Spherical Riemann stereographic projection coordinates to complex number coordinates.

complex_to_spherical(s)

Complex coordinates to to Spherical Riemann stereographic projection coordinates.

complex_to_spherical_riemann

torchlaplace.transformations.complex_to_spherical_riemann(s_real, s_imag)

Complex coordinates to to Spherical Riemann stereographic projection coordinates. I.e. we can translate any complex number \(s\in \mathbb{C}\) into a coordinate on the Riemann Sphere \((\theta, \phi) \in \mathcal{D} = (-{\pi}, {\pi}) \times (-\frac{\pi}{2}, \frac{\pi}{2})\), i.e.

\[\begin{aligned} u(s) = \left( \arctan \left( \frac{\Im(s)}{\Re(s)} \right),\arcsin \left( \frac{|s|^2-1}{|s|^2+1} \right) \right) \end{aligned}\]

For more details see [1].

Parameters

  • s_real (Tensor) – Real component of the complex tensor, of shape \((\text{dimension})\).

  • s_imag (Tensor) – Imaginary component of the complex tensor, of shape \((\text{dimension})\).

Returns

Tuple Tensor of \((\theta, \phi)\) of complex number in spherical Riemann stereographic projection coordinates. Where the shape of \(\theta, \phi\) is of shape \((\text{dimension})\).

spherical_riemann_to_complex

torchlaplace.transformations.spherical_riemann_to_complex(theta, phi)

Spherical Riemann stereographic projection coordinates to complex number coordinates. I.e. inverse Spherical Riemann stereographic projection map.

The inverse transform, \(v: \mathcal{D} \rightarrow \mathbb{C}\), is given as

\[\begin{aligned} s = v(\theta, \phi) = \tan \left( \frac{\phi}{2} + \frac{\pi}{4} \right) e^{i \theta} \end{aligned}\]
Parameters

  • theta (Tensor) – Spherical Riemann stereographic projection coordinates, shape \(\theta\) component of shape \((\text{dimension})\).

  • phi (Tensor) – Spherical Riemann stereographic projection coordinates, shape \(\phi\) component of shape \((\text{dimension})\).

Returns

Tuple Tensor of real and imaginary components of the complex numbers coordinate, of \((\Re(s), \Im(s))\). Where \(s \in \mathbb{C}^d\), with \(d\) is \(\text{dimension}\).

spherical_to_complex

torchlaplace.transformations.spherical_to_complex(theta, phi)

Spherical Riemann stereographic projection coordinates to complex number coordinates. I.e. inverse Spherical Riemann stereographic projection map.

The inverse transform, \(v: \mathcal{D} \rightarrow \mathbb{C}\), is given as

\[\begin{aligned} s = v(\theta, \phi) = \tan \left( \frac{\phi}{2} + \frac{\pi}{4} \right) e^{i \theta} \end{aligned}\]

This uses torchlaplace.transformations.spherical_riemann_to_complex(), however provides maintains the shape of the input tensor and output tensor.

Parameters

  • theta (Tensor) – Spherical Riemann stereographic projection coordinates, shape \(\theta\) component of shape \((\text{Shape})\).

  • phi (Tensor) – Spherical Riemann stereographic projection coordinates, shape \(\phi\) component of shape \((\text{Shape})\).

Returns

Complex Tensor of the complex numbers coordinate, of shape \((\text{Shape})\).

complex_to_spherical

torchlaplace.transformations.complex_to_spherical(s)

Complex coordinates to to Spherical Riemann stereographic projection coordinates. I.e. we can translate any complex number \(s\in \mathbb{C}\) into a coordinate on the Riemann Sphere \((\theta, \phi) \in \mathcal{D} = (-{\pi}, {\pi}) \times (-\frac{\pi}{2}, \frac{\pi}{2})\), i.e.

\[\begin{aligned} u(s) = \left( \arctan \left( \frac{\Im(s)}{\Re(s)} \right),\arcsin \left( \frac{|s|^2-1}{|s|^2+1} \right) \right) \end{aligned}\]

For more details see [1].

This uses torchlaplace.transformations.complex_to_spherical_riemann(), however provides maintains the shape of the input tensor and output tensor.

Parameters

s (Tensor) – Complex tensor, of shape \((\text{Shape})\).

Returns

Tuple Tensor of \((\theta, \phi)\) of complex number in spherical Riemann stereographic projection coordinates. Where the shape of \(\theta, \phi\) each is of shape \((\text{Shape})\).