CoordMap¶

Various classes are defined to represent different coordinate mappings. They define the coordinate transformation (and its derivatives) so that the Reflection-Free Complex Absorbing Potentials and the virial operator can be easily discretized over the discretization grid.

The CoordMap class is the most basic one. It is an abstract class, requiring only a complex scaling angle \(\theta\) and a discretization grid.

The Uniform Complex Scaling (UCS) transformation \(F_{UCS}: x \mapsto x e^{i \theta}\) is easily derived from it in the UniformCoordMap class.

Another well-known transformation is the Exterior Complex Scaling (ECS), that leaves the potential unscaled inside a region \([-x_0, x_0]\) (i.e., \(F_{ECS}: x \mapsto x\)), while amounting to the UCS outside (i.e. \((x - x_0) e^{i \theta}\) for \(x > x_0\)). This has the advantage of leaving the innermost potential unscaled.

However, the most efficient coordinate transformations discussed in the literature (when it comes to finding Siegert states numerically) are know as Smooth Exterior Complex Scaling (SECS). Contrary to the usual ECS, there are smooth transitions between both regimes, hence their name. The sharpness of these transitions is then controlled by another parameter, \(\lambda\). The abstract base class SmoothExtCoordMap allows for the representation of such coordinate transformations.

A SECS generally relies on a function \(q\) that smoothly goes from 0 to 1 around \(\pm x_0\). This is why a SmoothFuncCoordMap class is also defined as an abstract base class deriving from the SmoothExtCoordMap class. In practice, all the implemented SECS implemented in SiegPy derive from the SmoothFuncCoordMap class.

There are two main possibilites to define a smooth coordinate transformations by using a smooth function \(q\):

\(F_{KG}: x \mapsto x e^{i \theta q(x)}\), that will be called the Kalita-Gupta (KG) coordinate transformation,
\(F_{S}: x \mapsto F_S(x)\) such that its derivative with respect to \(x\) is \(F_S^\prime = f_S: x \mapsto 1 + (e^{i \theta} - 1) q(x)\). This will be labeled as the Simon coordinate transformation.

This is the reason why two other abstract base classes were defined:

the KGCoordMap class,
and the SimonCoordMap class.

They both require a smooth function \(q\) as parameters.

Two main types of smooth functions are implemented in SiegPy: one based on the error function \(\text{erf}\), the other on \(\tanh\), hence giving rise to four classes that can readily be used to find Siegert states numerically:

the ErfKGCoordMap class,
the ErfSimonCoordMap class,
the TanhKGCoordMap class,
the TanhSimonCoordMap class.

See smoothfunctions for more details on the smooth functions.

class siegpy.coordinatemappings.CoordMap(theta, grid, GCVT)[source]¶

Bases: object

Note

This is an abstract class.

Base class of all the other coordinate mappings.

Parameters:	theta (float) – Complex scaling angle. grid (numpy array or None) – Discretization grid. GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to `True`, then only one virial value is computed, else there are one per coordinate mapping parameter.

theta¶

Returns:	Complex scaling angle.
Return type:	float

GCVT¶

Returns:	Parameter stating which virial operator(s) have to be used.
Return type:	bool

grid¶

Returns:	Discretization grid.
Return type:	numpy array

_to_be_updated(new_grid)[source]¶

Parameters:	new_grid (numpy array) – New discretization grid.
Returns:	`True` if the grid has to be updated.
Return type:	bool

values¶

Returns:	Values of the coordinate transorfmation.
Return type:	numpy array

f_values¶

Returns:	Values of the first derivative of the coordinate transorfmation.
Return type:	numpy array

f_dx_values¶

Returns:	Values of the second derivative of the coordinate transorfmation.
Return type:	numpy array

f_dx2_values¶

Returns:	Values of the third derivative of the coordinate transorfmation.
Return type:	numpy array

dxi_values¶

Returns:	Values of the first derivative with respect to all the parameters of the coordinate transorfmation.
Return type:	numpy array

f_dxi_values¶

Returns:	Values of the first derivative with respect to all the parameters of the first derivative of the coordinate transorfmation.
Return type:	numpy array

V0_values¶

Returns:	Values of the first additional RF-CAP.
Return type:	numpy array

V1_values¶

Returns:	Values of the second additional RF-CAP.
Return type:	numpy array

V2_values¶

Returns:	Values of the third additional RF-CAP.
Return type:	numpy array

U0_values¶

Returns:	Values of the first additional virial operator potential.
Return type:	numpy array

U1_values¶

Returns:	Values of the second additional virial operator potential.
Return type:	numpy array

U2_values¶

Returns:	Values of the third additional virial operator potential.
Return type:	numpy array

U11_values¶

Returns:	Values of the fourth additional virial operator potential.
Return type:	numpy array

_update_all_values()[source]¶: Update the values of the coordinate mapping and its derivatives with respect to \(x\) and with respect to the coordinate mapping parameters, as well as related quantities such as the Reflection-Free Complex Absorbing Potential and the virial operator.

_update_x_deriv_values()[source]¶: Update the values of the coordinate mapping and its three first derivatives with respect to \(x\).

_update_x_deriv_from_grid()[source]¶: Update the values of the coordinate mapping and its three first derivatives with respect to \(x\), if the grid is not None.

_update_param_deriv_values()[source]¶: Update the values of the derivative with respect to the coordinate mapping parameters of the coordinate mapping and its first derivative with respect to \(x\).

_update_param_deriv_from_grid()[source]¶: Update the values of the derivative with respect to the coordinate mapping parameters of the coordinate mapping and its first derivative with respect to \(x\), if the grid is not None.

_get_values(*args)[source]¶: Note

This is an abstract method.

Evaluate the values of the coordinate mapping with respect to \(x\).

_get_f_values(*args)[source]¶: Note

This is an abstract method.

Evaluate the values of the first derivative of the coordinate mapping with respect to \(x\).

_get_f_dx_values(*args)[source]¶: Note

This is an abstract method.

Evaluate the values of the second derivative of the coordinate mapping with respect to \(x\).

_get_f_dx2_values(*args)[source]¶: Note

This is an abstract method.

Evaluate the values of the third derivative of the coordinate mapping with respect to \(x\).

_get_dxi_values(*args)[source]¶: Note

This is an abstract method.

Evaluate the values of the first derivative of the coordinate mapping with respect to the coordinate mapping parameters.

_get_f_dxi_values(*args)[source]¶: Note

This is an abstract method.

Evaluate the values of the first derivative with respect to the coordinate mapping parameters of the first derivative with respect to \(x\) of the coordinate mapping.

_update_RFCAP_values()[source]¶: Update the various potentials used to define the Reflection-Free Complex Absorbing Potentials

_update_virial_values()[source]¶: Update the values of the different potentials used to define the various virial operators.

class siegpy.coordinatemappings.UniformCoordMap(theta, GCVT=True, grid=None)[source]¶

Bases: siegpy.coordinatemappings.CoordMap

The uniform coordinate transformation corresponds to: \(x \mapsto x e^{i \theta}\).

Parameters:	theta (float) – Complex scaling angle. GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to `True`, then only one virial value is computed, else there are one per parameter (here, `theta`). Defaults to `True`. grid (numpy array) – Discretization grid (optional).

_get_values()[source]¶

Returns:	Values of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_values()[source]¶

Returns:	Values of the first derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_dx_values()[source]¶

Returns:	Values of the second derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_dx2_values()[source]¶

Returns:	Values of the third derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_dxi_values()[source]¶

Returns:	Values of the first derivative of the coordinate mapping with respect to the coordinate mapping parameters.
Return type:	numpy array

_get_f_dxi_values()[source]¶

Returns:	Values of the first derivative with respect to the coordinate mapping parameters of the first derivative with respect to \(x\) of the coordinate mapping.
Return type:	numpy array

class siegpy.coordinatemappings.SmoothExtCoordMap(theta, x0, lbda, GCVT, grid)[source]¶

Bases: siegpy.coordinatemappings.CoordMap

Note

This is an abstract class.

This is the base class for all the other classes implementing a particular type of smooth exterior complex scaling.

Warning

This class must be used to create child classes if no smooth function is actually required.

Parameters:

theta (float) – Complex scaling angle.
x0 (float) – Inflection point.
lbda (float) – Sharpness parameter
GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to True, then only one virial value is computed, else there are three, one for each parameter (here, theta, x0 and lbda).
grid (numpy array or None) – Discretization grid.

Raises:

ValueError – If the x0 or lbda is not positive.

x0¶

Returns:	Inflection point.
Return type:	float

lbda¶

Returns:	Sharpness paramter.
Return type:	float

class siegpy.coordinatemappings.SmoothFuncCoordMap(theta, smooth_func, GCVT, grid)[source]¶

Bases: siegpy.coordinatemappings.SmoothExtCoordMap

Note

This is an abstract class.

Class used to define methods that may not be generally shared by any type of SmoothExtCoordMap child classes, because a Smooth Exterior Coordinate Mapping could be defined without an explicit use of a smooth function.

Warning

This class must be used to create child classes if a smooth function is required.

Parameters:	theta (float) – Complex scaling angle. smooth_func (SmoothFunction) – Smooth function \(q\). GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to `True`, then only one virial value is computed, else there are one per coordinate mapping parameter (including `theta` here). grid (numpy array or None) – Discretization grid.

smooth_func¶

Returns:	Smooth function \(q\).
Return type:	SmoothFunction

_update_all_values()[source]¶: Update the grid and values of the smooth function before using the parent method updating all other values.

_get_gp_and_gm()[source]¶

Note

This function only avoids code repetition in child classes.

Returns:	Two numpy arrays that are often used by the child classes, while only being based on properties.
Return type:	tuple made of two numpy arrays

class siegpy.coordinatemappings.SimonCoordMap(theta, smooth_func, GCVT, grid)[source]¶

Bases: siegpy.coordinatemappings.SmoothFuncCoordMap

Note

This is an abstract class.

This class allows the representation of the smooth exterior coordinate mapping \(F: x \mapsto F(x)\) such that its derivative with respect to \(x\) is equal to \(1 + (e^{i \theta} - 1) q(x)\), where \(q\) is a smooth function.

Parameters:	theta (float) – Complex scaling angle. smooth_func (SmoothFunction) – Smooth function \(q\). GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to `True`, then only one virial value is computed, else there are one per coordinate mapping parameter (including `theta` here). grid (numpy array or None) – Discretization grid.

_update_x_deriv_from_grid()[source]¶: Update the values of the coordinate mapping and its three first derivatives with respect to \(x\), if the grid is not None.

_update_param_deriv_from_grid()[source]¶: Update the values of the derivative with respect to the coordinate mapping parameters of the coordinate mapping and its first derivative with respect to \(x\).

_get_values(m)[source]¶

Parameters:	m (numpy array) – Values of the intermediary function which is the factor of \((e^{i \theta} - 1)\) term in the coordinate mapping function.
Returns:	Values of the second derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_values()[source]¶

Returns:	Values of the first derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_dx_values()[source]¶

Returns:	Values of the second derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_dx2_values()[source]¶

Returns:	Values of the third derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_dxi_values(m, m_dx0, m_dl)[source]¶

Parameters:	m (numpy array) – Values of the intermadiary function. m_dx0 (numpy array) – First derivative of the intermediary function with respect to `x0`. m_dl (numpy array) – First derivative of the intermediary function with respect to the sharpness parameter.
Returns:	Values of the first derivative of the coordinate mapping with respect to the coordinate mapping parameters.
Return type:	numpy array

_get_f_dxi_values()[source]¶

Returns:	Values of the first derivative with respect to the coordinate mapping parameters of the first derivative with respect to \(x\) of the coordinate mapping.
Return type:	numpy array

_get_m_values(grid, lbda, gp, gm)[source]¶

Note

This is an abstract method.

Parameters:	grid (numpy array) – Discretization grid. lbda (float) – Sharpness parameter gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of an intermediate function.
Return type:	numpy array

_get_m_dx0_values(grid, lbda, gp, gm)[source]¶

Note

This is an abstract method.

Parameters:	grid (numpy array) – Discretization grid. lbda (float) – Sharpness parameter gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of the first derivative with respect to `x0` of an intermediate function.
Return type:	numpy array

_get_m_dl_values(grid, lbda, gp, gm)[source]¶

Note

This is an abstract method.

Parameters:	grid (numpy array) – Discretization grid. lbda (float) – Sharpness parameter gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of the first derivative with respect to the sharpness parameter `lambda` of an intermediate function.
Return type:	numpy array

class siegpy.coordinatemappings.TanhSimonCoordMap(theta, x0, lbda, GCVT=True, grid=None)[source]¶

Bases: siegpy.coordinatemappings.SimonCoordMap

This class defines the smooth exterior coordinate mapping of the Simon type using the smooth function based on \(\tanh\).

Parameters:

theta (float) – Complex scaling angle.
x0 (float) – Inflection point.
lbda (float) – Sharpness parameter
GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to True, then only one virial value is computed, else there are one per coordinate mapping parameter (here, theta, x0 and lbda). Defaults to True.
grid (numpy array or None) – Discretization grid (optional).

_get_m_values(gp, gm)[source]¶

Parameters:	gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of an intermediate function.
Return type:	numpy array

_get_m_dx0_values(gp, gm)[source]¶

Parameters:	gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of the first derivative with respect to `x0` of an intermediate function.
Return type:	numpy array

_get_m_dl_values(gp, gm)[source]¶

Parameters:	gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of the first derivative with respect to the sharpness parameter `lambda` of an intermediate function.
Return type:	numpy array

class siegpy.coordinatemappings.ErfSimonCoordMap(theta, x0, lbda, GCVT=True, grid=None)[source]¶

Bases: siegpy.coordinatemappings.SimonCoordMap

This class defines the smooth exterior coordinate mapping of the Simon type using the smooth function based on \(\text{erf}\).

Parameters:

theta (float) – Complex scaling angle.
x0 (float) – Inflection point.
lbda (float) – Sharpness parameter
GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to True, then only one virial value is computed, else there are one per coordinate mapping parameter (here, theta, x0 and lbda). Defaults to True.
grid (numpy array or None) – Discretization grid (optional).

_get_m_values(gp, gm)[source]¶

Parameters:	gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of an intermediate function.
Return type:	numpy array

_get_m_dx0_values(gp, gm)[source]¶

Parameters:	gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of the first derivative with respect to `x0` of an intermediate function.
Return type:	numpy array

_get_m_dl_values(gp, gm)[source]¶

Parameters:	gp (numpy array) – Intermadiary value. gm (numpy array) – Intermadiary value.
Returns:	The values of the first derivative with respect to the sharpness parameter `lambda` of an intermediate function.
Return type:	numpy array

class siegpy.coordinatemappings.KGCoordMap(theta, smooth_func, GCVT, grid)[source]¶

Bases: siegpy.coordinatemappings.SmoothFuncCoordMap

Note

This is an abstract class.

This class allows the representation of the smooth exterior coordinate mapping \(F: x \mapsto x e^{i \theta q(x)}\), that we will call the Kalita-Gupta (KG) coordinate mapping. \(q\) represents the smooth function.

Parameters:	theta (float) – Complex scaling angle. smooth_func (SmoothFunction) – Smooth function \(q\). GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to `True`, then only one virial value is computed, else there are one per coordinate mapping parameter (including `theta` here). grid (numpy array or None) – Discretization grid.

_update_x_deriv_from_grid()[source]¶: Update the values of the coordinate mapping and its three first derivatives with respect to \(x\), if the grid is not None.

_update_param_deriv_from_grid()[source]¶: Update the values of the derivative with respect to the coordinate mapping parameters of the coordinate mapping and its first derivative with respect to \(x\).

_get_values()[source]¶

Returns:	Values of the second derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_values(F)[source]¶

Parameters:	F (numpy array) – Values of the coordinate mapping.
Returns:	Values of the first derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_dx_values(F, f)[source]¶

Parameters:	F (numpy array) – Values of the coordinate mapping. f (numpy array) – Values of the first derivative of the coordinate mapping with respect to \(x\).
Returns:	Values of the second derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_f_dx2_values(F, f, f_dx)[source]¶

Parameters:	F (numpy array) – Values of the coordinate mapping. f (numpy array) – Values of the first derivative of the coordinate mapping with respect to \(x\). f_dx (numpy array) – Values of the second derivative of the coordinate mapping with respect to \(x\).
Returns:	Values of the third derivative of the coordinate mapping with respect to \(x\).
Return type:	numpy array

_get_dxi_values(*args)[source]¶: Does nothing, as its role is already performed by the _update_param_deriv_from_grid() method

_get_f_dxi_values(F, F_dth, F_dx0, F_dl)[source]¶

Parameters:	F (numpy array) – Values of the coordinate mapping. F_dth (numpy array) – Values of the first derivative of the coordinate mapping with respect to the complex scaling angle. F_dx0 (numpy array) – Values of the second derivative of the coordinate mapping with respect to `x0`. F_dl (numpy array) – Values of the first derivative of the coordinate mapping with respect to the sharpness parameter.
Returns:	Values of the first derivative with respect to the coordinate mapping parameters of the first derivative with respect to \(x\) of the coordinate mapping.
Return type:	numpy array

class siegpy.coordinatemappings.TanhKGCoordMap(theta, x0, lbda, GCVT=True, grid=None)[source]¶

Bases: siegpy.coordinatemappings.KGCoordMap

This class defines the smooth exterior coordinate mapping of the Kalita-Gupta type using the smooth function based on \(\tanh\).

Parameters:

theta (float) – Complex scaling angle.
x0 (float) – Inflection point.
lbda (float) – Sharpness parameter
GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to True, then only one virial value is computed, else there are one per coordinate mapping parameter (here, theta, x0 and lbda). Defaults to True.
grid (numpy array or None) – Discretization grid (optional).

class siegpy.coordinatemappings.ErfKGCoordMap(theta, x0, lbda, GCVT=True, grid=None)[source]¶

Bases: siegpy.coordinatemappings.KGCoordMap

This class defines the smooth exterior coordinate mapping of the Kalita-Gupta type using the smooth function based on \(\text{erf}\).

Parameters:

theta (float) – Complex scaling angle.
x0 (float) – Inflection point.
lbda (float) – Sharpness parameter
GCVT (bool) – Stands for Generalized Complex Virial Theorem. If it is set to True, then only one virial value is computed, else there are one per coordinate mapping parameter (here, theta, x0 and lbda). Defaults to True.
grid (numpy array) – Discretization grid (optional).