AnalyticBasisSet¶

This abstract base class is meant to implement the main methods available to all basis set classes that are specific to an analytical case. This ensures that all analytical cases have the same basic API, while avoiding code repetition.

As an example, it is used to define the SWPBasisSet class, which is the specific basis set class for the analytical 1D Square-Well potential case. You might notice that only a few methods were implemented there.

class siegpy.analyticbasisset.AnalyticBasisSet(states=None)[source]¶

Bases: siegpy.basisset.BasisSet

This should be the base class for the specific basis set classes of any analytic cases available in SiegPy.

Its methods allow to compute most the main quantities and forces the child classes to implement the other ones.

For instance, any relevant Siegert state expansion (such as the Mittag-Leffler Expansion (MLE), which uses all Siegert states with a weight 1/2, or the Berggren expansion, which uses only bound and resonant states with a weight 1) of the quantities of interest (such as the completeness relation (CR), zero operator, strength function, strength function and time-propagation must therefore be defined here, as they should be valid for any analytical case.

On the other hand, all the methods used to define the analytical eigenstates must be implemented by the child classes.

An AnalyticBasisSet instance is initialized from a list of AnalyticEigenstate instances.

Parameters:	states (list) – Analytic eigenstates of a Hamiltonian. If `None`, it means that the BasisSet instance is empty.
Raises:	`ValueError` – If any state comes from a different potential than the others.

classmethod from_file(filename, grid=None, analytic=True, nres=None, kmax=None, bounds_only=False)[source]¶

Read a basis set from a binary file.

Parameters:	filename (str) – Name of a file containing a basis set. grid (numpy array or list or set) – Discretization grid of the wavefunctions of the Siegert states (optional). analytic (bool) – If `True`, the scalar products will be computed analytically. nres (int) – Number of resonant couples in the Siegert basis set created (optional). kmax (float) – Value of the maximal continuum wavenumber in the returned basis set, also containing the bound states, if there were any in the file (optional). bounds_only (bool) – If `True`, the basis set returned contains only bound states.
Returns:	The basis set read from the file.
Return type:	AnalyticBasisSet

Examples

All the examples given below are given for the SWP analytical case, but could be easily adapted for any other analytical cases.

A basis set is read from a file in the following manner:

>>> from siegpy import SWPBasisSet
>>> filename = "doc/notebooks/siegerts.dat"
>>> bs = SWPBasisSet.from_file(filename)

It contains a certain number of states, with a given discretization grid (here, the grid is None) and analyticity:

>>> len(bs)
566
>>> bs.grid
>>> assert bs.analytic == True

It is possible to update the grid (and the values of the eigenstates at the same time) in the 1D SW potential case:

>>> bs = SWPBasisSet.from_file(filename, grid=[-2, -1, 0, 1, 2])
>>> bs.grid
array([-2, -1,  0,  1,  2])
>>> print(bs[0].values)
[ 0.18053285+0.j  0.51185847+0.j  0.63921710-0.j  0.51185847-0.j
  0.18053285-0.j]

The analyticity of the states can also be updated:

>>> bs = SWPBasisSet.from_file(filename, analytic=False)
>>> assert bs.analytic == False

If required, only the bound states are read:

>>> bounds = SWPBasisSet.from_file(filename, bounds_only=True)
>>> assert len(bounds) == len(bs.bounds)

The number of resonant and antiresonant states can also be chosen:

>>> siegerts = SWPBasisSet.from_file(filename, nres=5)
>>> assert len(siegerts.bounds) == len(bs.bounds)
>>> assert len(siegerts.antibounds) == len(bs.antibounds)
>>> assert len(siegerts.resonants) == 5
>>> assert len(siegerts.antiresonants) == 5

If the basis set contains continuum states, it is also possible to keep only the states whose wavenumber is smaller than kmax (in addition to the bound states).

classmethod find_Siegert_states()[source]¶

Note

This is an asbtract class method.

Initialize a basis made of Siegert states found analytically.

Returns:	A basis set made of `AnalyticSiegert` instances.
Return type:	AnalyticBasisSet

classmethod find_continuum_states(*args, **kwargs)[source]¶

Note

This is an asbtract class method.

Initialize a basis made of continuum states found analytically.

Returns:	A basis set made of `AnalyticContinuum` instances.
Return type:	AnalyticBasisSet

grid¶

Returns:	Value of the discretization grid of all the states in the basis set.
Return type:	numpy array or None
Raises:	`ValueError` – If at least one state has a different grid than the others or if the basis set is empty.

Examples

In the following example, the states have no grid:

>>> from siegpy import SWPBasisSet
>>> siegerts = SWPBasisSet.from_file("doc/notebooks/siegerts.dat")
>>> siegerts.grid is None
True

You can also use the grid attribute to update the grid (and therefore all the values of the wavefunctions) of the states in the analytic basis set at the same time:

>>> xgrid = [-1, 0, 1]
>>> siegerts.grid = xgrid
>>> siegerts[-1].grid
array([-1,  0,  1])

analytic¶

Returns:	Value of the `analytic` attribute of all the states in the basis set.
Return type:	bool
Raises:	`ValueError` – If some states have different value for `analytic` or if the basis set is empty.

Examples

In the following example, all the states require analytic scalar products:

>>> from siegpy import SWPBasisSet
>>> siegerts = SWPBasisSet.from_file("doc/notebooks/siegerts.dat")
>>> siegerts.analytic
True

You can also use the analytic attribute to update the values for all the states in the basis set at the same time:

>>> siegerts.analytic = False
>>> all([state.analytic == False for state in siegerts])
True

potential¶

Returns:	Potential of all the states in the basis set.
Return type:	Potential
Raises:	`ValueError` – If some states come from a different potential or if the basis set is empty.

Example

>>> from siegpy import SWPBasisSet
>>> siegerts = SWPBasisSet.from_file("doc/notebooks/siegerts.dat")
>>> siegerts.potential
1D Square-Well Potential of width 4.44 and depth 10.00

plot_wavefunctions(nres=None, xlim=None, ylim=None, title=None, file_save=None)[source]¶

Plot the bound, resonant and anti-resonant wavefunctions of the basis set along with the potential. The continuum and anti-bound states, if any are present in the basis set, are not plotted.

The wavefunctions are translated along the y-axis by their energy (for bound states) or absolute value of their energy (for resonant and anti-resonant states).

Parameters:

nres (int) – Number of resonant and antiresonant wavefunctions to plot.
xlim (tuple(float or int, float or int)) – Range of the x axis of the plot (optional)
ylim (tuple(float or int, float or int)) – Range of the y axis of the plot (optional)
title (str) – Plot title (optional).
file_save (str) – Filename of the plot to be saved (optional)

Raises:

ValueError – If the minimum of the potential cannot be found.

plot_wavenumbers(xlim=None, ylim=None, title=None, file_save=None)[source]¶

Plot the wavenumbers of the Siegert states in the basis set.

Parameters:	xlim (tuple(float or int, float or int)) – Range of the x axis of the plot (optional). ylim (tuple(float or int, float or int)) – Range of the y axis of the plot (optional). title (str) – Plot title (optional). file_save (str) – Filename of the plot to be saved (optional).

plot_energies(xlim=None, ylim=None, title=None, file_save=None)[source]¶

Plot the energies of the Siegert states in the basis set.

Parameters:	xlim (tuple(float or int, float or int)) – Range of the x axis of the plot (optional). ylim (tuple(float or int, float or int)) – Range of the y axis of the plot (optional). title (str) – Plot title (optional). file_save (str) – Filename of the plot to be saved (optional).

MLE_contributions_to_CR(test)[source]¶

Evaluate the contribution of each state of the basis set to the completeness relation, according to the Mittag-Leffler Expansion.

Each element of the array is defined by: .. math:

\frac{ \left\langle test | \varphi_S \right)
\left( \varphi_S | test \right\rangle }
{2 \left\langle test | test \right\rangle}

where \(\varphi_S\) is a Siegert state of the basis set.

Parameters:	test (Function) – Test function
Returns:	Contribution of each state of the basis set to the completeness relation acording to the Mittag-Leffler Expansion of the completeness relation.
Return type:	numpy array

MLE_contributions_to_zero_operator(test)[source]¶

Evaluate the contribution of each state of the basis set to the zero operator, according to the Mittag-Leffler Expansion.

Each element of the returned array is defined by:

\[\frac{ \left\langle test | \varphi_S \right) \left( \varphi_S | test \right\rangle } {2 k_S \left\langle test | test \right\rangle}\]

where \(k_s\) is the wavenumber of the Siegert state \(\varphi_S\)

Parameters:	test (Function) – Test function.
Returns:	Contribution of each state of the basis set to the zero operator acording to the Mittag-Leffler Expansion of the zero operator.
Return type:	numpy array

MLE_completeness(test, nres=None)[source]¶

Evaluate the value of the Mittag-Leffler Expansion of the completeness relation using all Siegert states in the basis set for a given test function.

Returns the result of the following sum over all Siegert states \(varphi_S\):

\[\sum_S \frac{ \left\langle test | \varphi_S \right) \left( \varphi_S | test \right\rangle } {2 \left\langle test | test \right\rangle}\]

Parameters:	test (Function) – Test function. nres (int) – Number of (anti-)resonant states to use (optional).
Returns:	Evaluation of the completeness of the basis set using the Mittag-Leffler Expansion.
Return type:	float

MLE_zero_operator(test, nres=None)[source]¶

Evaluate the value of the Mittag-Leffler Expansion of the zero operator using all Siegert states in the basis set for a given test function.

Returns the result of the following sum over all Siegert states:

\[\sum_S \frac{ \left\langle test | \varphi_S \right) \left( \varphi_S | test \right\rangle } { 2 k_S \left\langle test | test \right\rangle }\]

where \(k_s\) is the wavenumber of the Siegert state \(\varphi_S\)

Parameters:	test (Function) – Test function. nres (int) – Number of (anti-)resonant states to use (optional).
Returns:	Evaluation of the zero operator of the basis set using the Mittag-Leffler Expansion.
Return type:	float

exact_completeness(test, hk=None, kmax=None)[source]¶

Evaluate the exact completeness relation using the bound states of the basis set and the continuum states defined by either hk and kmax (respectively the grid-step and maximum wavenumber of the grid of continuum states) or all the continuum states in the basis set.

Parameters:	test (Function) – Test function. hk (float) – Grid step for the wavenumbers of the “on-the-fly” continuum basis sets (optional). kmax (float) – Maximal wavenumber of the “on-the-fly” continuum basis set (optional).
Returns:	Value of the exact completeness relation, using bound and continuum states.
Return type:	float

continuum_contributions_to_CR(test, hk=None, kmax=None)[source]¶

Note

This is an asbtract class method.

Evaluate the continuum contributions to the completeness relation.

Parameters:

test (Function) – Test function.
hk (float) – Grid step for the wavenumbers of the “on-the-fly” continuum basis sets (optional).
kmax (float) – Maximal wavenumber of the “on-the-fly” continuum basis set (optional).

Returns:

numpy array – Contribution of each continuum state of the basis set to the exact completeness relation.
r

MLE_completeness_convergence(test, nres=None)[source]¶

Evaluate the convergence of the Mittag-Leffler Expansion of the completeness relation for the basis set, given a test function.

Parameters:	test (Function) – Test function. nres (int) – Number of (anti-)resonant states to use (default: use all of them).
Returns:	Two arrays of the same length. The first one is made of the absolute value of the resonant wavenumbers, while the second one is made of the values of the convergence of the MLE of the completeness relation.
Return type:	tuple(numpy array, numpy array)

Berggren_completeness_convergence(test, nres=None)[source]¶

Evaluate the convergence of the CR using the Berggren expansion.

Parameters:	test (Function) – Test function. nres (int) – Number of resonant states to use (default: use all of them).
Returns:	Two arrays of the same length. The first one is made of the absolute value of the resonant wavenumbers, while the second one is made of the values of the convergence of the Berggren expansion of the completeness relation.
Return type:	tuple(numpy array, numpy array)

MLE_zero_operator_convergence(test, nres=None)[source]¶

Evaluate the convergence of the Mittag-Leffler Expansion of the zero operator for the basis set, given a test function.

Parameters:	test (Function) – Test function. nres (int) – Number of (anti-)resonant states to use (default: use all of them).
Returns:	Two arrays of the same length. The first one is made of the absolute value of the resonant wavenumbers, while the second one is made of the values of the convergence of the MLE of the zero operator.
Return type:	tuple(numpy array, numpy array)

exact_completeness_convergence(test, hk=None, kmax=None)[source]¶

Evaluate the convergence of the exact completeness relation (using the continuum and bound states of the basis set) for a given test function.

A set of continuum states is defined on-the-fly if the values of both hk and kmax are not None (otherwise, the continuum states of the basis set, if any, are used).

Parameters:	test (Function) – Test function. hk (float) – Grid step for the wavenumbers of the “on-the-fly” continuum basis sets (optional). kmax (float) – Maximal wavenumber of the “on-the-fly” continuum basis set (optional).
Returns:	Two arrays of the same length. The first one is made of the continuum wavenumbers, while the second is made of the values of the convergence of the exact completeness relation.
Return type:	tuple(numpy array, numpy array)

plot_completeness_convergence(test, hk=None, kmax=None, nres=None, exact=True, MLE=True, title=None, file_save=None)[source]¶

Plot the convergence of both the Mittag-Leffler Expansion and the exact completeness relation for a given test function.

The exact convergence is computed on-the-fly (i.e. without the need to have continuum states in the basis set):

if hk and kmax are not None,
if exact and MLE are set to True and if the basis set does not contain enough continuum states to reach the absolute value of the last resonant wavenumber used (kmax is therefore defined by the wavenumber of the last resonant state used in the MLE of the CR, and hk is set to a default value)

Parameters:

test (Function) – Test function.
hk (float) – Grid step for the wavenumbers of the “on-the-fly” continuum basis sets (optional).
kmax (float) – Maximal wavenumber of the “on-the-fly” continuum basis set (optional).
nres (int) – Number of resonant couples contributions to be plotted (optional).
exact (bool) – If True, allows the plot of the exact strength function.
MLE (bool) – If True, allows the plot of the Mittag-Leffler Expansion of the strength function.
title (str) – Plot title (optional).
file_save (str) – Filename of the plot to be saved (optional).

MLE_strength_function(test, kgrid)[source]¶

Evaluate the Mittag-Leffler expansion of the strength function for a given test function. The test function is discretized on a grid of wavenumbers kgrid.

Parameters:	test (Function) – Test function. kgrid (numpy array) – Wavenumbers for which the strength function is evaluated.
Returns:	MLE of the strength function evaluated over the wavenumber grid `kgrid`.
Return type:	numpy array

exact_strength_function(test, kgrid, eta=None)[source]¶

Evaluate the exact strength function over a given wavenumber grid kgrid for a given a test function.

eta is an infinitesimal used to make the integration over the continuum states possible (the poles along the real axis being avoided).

Parameters:	test (Function) – Test function. kgrid (numpy array) – Wavenumbers for which the strength function is evaluated. eta (float) – Infinitesimal for integration (if `None`, default to 10 times the value of the grid-step of the continuum basis set).
Returns:	Exact strength function evaluated on the grid of wavenumbers `kgrid`.
Return type:	numpy array

exact_strength_function_OTF(test, kgrid, hk=0.0001, eta=None, tol=0.0001)[source]¶

Evaluate the exact strength function “on-the-fly” over a given wavenumber grid kgrid for a given a test function.

It is not necessary to have continuum states in the basis set to compute the exact strength function, because they can be computed “on-the-fly” (hence OTF). This even leads to a quicker evaluation of the strength function because the integral, to be compute for each point of kgrid, actually has an integrand that peaks around each particular value of kgrid and quickly vanishes around its maximum.

Such a minimal approximated integrand is constructed by using only the continuum states aroud the point of the kgrid considered, given the tolerance parameter tol. It allows to reach smaller values of hk and eta, and therefore more precise results, in a shorter amount of time.

Parameters:	test (Function) – Test function. kgrid (numpy array) – Wavenumbers for which the strength function is evaluated. hk (float) – Grid step for the wavenumbers of the “on-the-fly” continuum basis sets (optional). eta (float) – Infinitesimal for integration (if `None`, default to 10 times the value of the grid-step of the continuum basis set). tol (float) – Tolerance value to truncate the integrand function (ratio of the value of a possible new point of the integrand to the maximal value of the integrand).
Returns:	Approximate exact strength function evaluated on the grid of wavenumbers `kgrid`.
Return type:	numpy array

static _evaluate_integrand(q, k, test, eta, potential)[source]¶

Note

This is an asbtract class method.

Evaluate the integrand used to compute the strength function “on-the-fly”. It must be implemented in the child class.

Parameters:

q (float) – Wavenumber of the continuum state considered.
k (float) – Wavenumber for which the strength function is evaluated.
test (Function) – Test function.
eta (float) – Infinitesimal for integration (if None, default to 10 times the value of the grid-step of the continuum basis set).
potential (Potential) – Potential of the currently studied analytical case.

plot_strength_function(test, kgrid, nres=None, exact=True, MLE=True, bnds_abnds=False, title=None, file_save=None)[source]¶

Plot the convergence of both the Mittag-Leffler Expansion and the exact strength function for a given test function.

The exact convergence is computed on-the-fly (without the need to have continuum states in the BasisSet self).

Parameters:

test (Function) – Test function.
kgrid (numpy array) – Wavenumbers for which the strength function is evaluated.
nres (int) – Number of resonant couples contributions to be plotted (default to None, meaning that none are plotted; if nres=0, then only the sum of the bound and anti-bound states contributions is plotted).
exact (bool) – If True, allows the plot of the exact strength function.
MLE (bool) – If True, allows the plot of the Mittag-Leffler Expansion of the strength function.
bnds_abnds (bool) – If True, allows to plot the individual contributions of the bound and anti-bound states.
title (str) – Plot title (optional).
file_save (str) – Filename of the plot to be saved (optional).

exact_propagation(test, time_grid)[source]¶

Evaluate the exact time-propagation of a wavepacket test over a given time grid (made of positive numbers only).

Parameters:	test (Function) – Test function. time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only.
Returns:	Exact propagated wavepacket for the different times of `time_grid`.
Return type:	2D numpy array

exact_propagation_OTF(test, time_grid, kmax, hk)[source]¶

Evaluate the exact time-propagation of a given test function for a given time grid after an on-the-fly creation of the continuum states given the values of kmax and hk.

Parameters:

test (Function) – Test function.
time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only.
hk (float) – Grid step for the wavenumbers of the “on-the-fly” continuum basis sets (optional).
kmax (float) – Maximal wavenumber of the “on-the-fly” continuum basis set (optional).

Returns:

returns: Exact propagated wavepacket for the different times – of time_grid.
rtype: 2D numpy array

MLE_propagation(test, time_grid)[source]¶

Evaluate the Mittag-Leffler Expansion of the time-propagation of a test wavepacket over a given time grid.

Parameters:	test (Function) – Test function. time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only.
Returns:	MLE of the propagated wavepacket for the different times of `time_grid`.
Return type:	2D numpy array

Berggren_propagation(test, time_grid)[source]¶

Evaluate the Berggren Expansion of the time-propagation of a test wavepacket over a given time grid.

Parameters:	test (Function) – Test function. time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only.
Returns:	Berggren expansion of the propagated wavepacket for the different times of `time_grid`.
Return type:	2D numpy array

Siegert_propagation(test, time_grid, weights=None)[source]¶

Evaluate a user-defined expansion over the Siegert states of the time-propagation of a test wavepacket over a given time grid.

The user chooses the weight of each type of Siegert states of the basis set. If no weights are passed, then exact Siegert states expansion is performed.

Parameters:	test (Function) – Test function. time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only. weights (dict) – Dictionary of the weights to use for the time-propagation. Keys correspond to a type of Siegert states (‘ab’ for anti-bounds, ‘b’ for bounds, ‘r’ for resonants and ‘ar’ for anti-resonants) and the corresponding value is the weight to use for all the states of the given type (optional).
Returns:	Siegert states expansion of the propagated wavepacket for the different times of `time_grid`.
Return type:	2D numpy array
Raises:	`KeyError` – If an invalid key is found in `weights`.

exact_Siegert_propagation(test, time_grid)[source]¶

Evaluate the exact Siegert propagation of the initial wavepacket test for the times of time_grid. In contrast with all other expansions for the propagation, the time-evolution of the Siegert states is not only due to an exponential, but also to state- and time-dependent weights (see eq. 69 of Santra et al., PRA 71 (2005)).

There is no need to define any weight, since the correct weight is known analytically.

Parameters:	test (Function) – Test function. time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only.
Returns:	Exact Siegert expansion of the propagated wavepacket for the different times of `time_grid`.
Return type:	2D numpy array
Raises:	`BasisSetError` – If the basis set contains no Siegert states.

_propagate(test, time_grid, weights=None)[source]¶

Evaluate the time-propagation of a test wavepacket as the matrix product of two matrices: one to account for the time dependance of the propagation of the wavepacket (mat_time), the other for its space dependance (mat_space).

The contribution of the continuum states to the time propagation of the wavepacket requires a numerical integration that is performed using the composite Simpson’s rule.

The contribution of the Siegert states to the time propagation of the wavepacket is computed through a discrete sum over all the Siegert states, with a user-defined weight for each type of Siegert states.

Parameters:	test (Function) – Test function. time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only. weights (dict) – Dictionary of the weights to use for the time-propagation. Keys correspond to a type of Siegert states (‘ab’ for anti-bounds, ‘b’ for bounds, ‘r’ for resonants and ‘ar’ for anti-resonants) and the corresponding value is the weight to use for all the states of the given type (optional).
Returns:	Propagated wavepacket for the different times of `time_grid`.
Return type:	2D numpy array
Raises:	`BasisSetError` – If the basis set does not contain Siegert nor continuum states.

_add_one_continuum_state()[source]¶

Note

This is an asbtract class method.

Add a continuum state to the basis set, depending on the already existing continuum states.

Returns:	Instance of the child class with one more continuum state.
Return type:	AnalyticBasisSet

plot_propagation(test, time_grid, exact=True, exact_Siegert=True, MLE=False, Berggren=False, xlim=None, ylim=None, title=None, file_save=None)[source]¶

Plot the time propagation of a wavepacket using either the exact expansion (using bound and continuum states), the exact Siegert states expansion, the Mittag-Leffler Expansion or the Berggren expansion over a given time grid.

Any of these expansions can be turned on or off by setting the corresponding optional arguments (exact, exact_Siegert, MLE and Berggren respectively) to True or False. By default, both exact expansions are plotted.

Parameters:

test (Function) – Test function.
time_grid (numpy array or list of positive numbers) – Times for which the propagation is evaluated. It must contain positive numbers only.
exact (bool) – If True, allows the plot of the exact time-propagation (using bound and continuum states).
exact_Siegert (bool) – If True, allows the plot of the exact time-propagation (using all Siegert states).
MLE (bool) – If True, allows the plot of the Mittag-Leffler Expansion of the time-propagation.
Berggren (bool) – If True, allows the plot of the Berggren expansion of the time-propagation.
xlim (tuple(float or int, float or int)) – Range of the x axis of the plot (optional).
xlim – Range of the y axis of the plot (optional).
title (str) – Plot title (optional).
file_save (str) – Base name of the files where the plots are to be saved (optional).