Test functions

Below are presented the classes that are mainly used as test functions when it comes to evaluate the completeness relation, response function or time-propagation.

Such classes are:

class siegpy.functions.Rectangular(xl, xr, k0=0.0, h=1.0, grid=None)[source]

Bases: siegpy.functions.AnalyticFunction

A rectangular function is characterized by:

In addition to the behaviour of an analytic function:

  • the norm is computed analytically,
  • the attribute is_even returns True if the rectangular function is centered, even if the discretization grid is not centered,
  • the equality and addition of two rectangular functions are also defined.
Parameters:
  • xl (float) – Left border of the rectangular function.
  • xr (float) – Right border of the rectangular function.
  • k0 (float) – Initial momentum of the rectangular function (default to 0).
  • h (float) – Maximal amplitude of the rectangular function (default to 1).
  • grid (list or set or numpy array) – Discretization grid (optional).
Raises:

  • ValueError – If the amplitude h is zero or if the width is negative.

  • Examples

  • A rectangular function has several attributes:

  • >>> r = Rectangular(-4, 2, k0=5)

  • >>> r.xl

  • -4

  • >>> r.xr

  • 2

  • >>> r.width

  • 6

  • >>> r.center

  • -1.0

  • >>> r.momentum

  • 5

  • >>> r.amplitude

  • 1.0

  • If no discretization grid is passed, then the atrributes

  • grid and

  • values are set to

  • None:

  • >>> r.grid is None and r.values is None

  • True

  • If a grid is passed, then the rectangular function is

  • discretized (meaning its attribute

  • values is not

  • None):

  • >>> r1 = Rectangular(-4, 2, k0=5, grid=[-1, 0, 1])

  • >>> r2 = Rectangular(-4, 2, k0=5, h=2, grid=[-1, 0, 1])

  • >>> np.array_equal(r2.values, 2*r1.values)

  • True

  • .. note:: – The only way of modifying the values of a Rectangular instance is by setting a new grid:

    >>> r.grid = [-1, 0, 1]
>>> assert np.array_equal(r.grid, r1.grid)
>>> assert np.array_equal(r.values, r1.values)
>>> r.values = [2, 1, 2]
Traceback (most recent call last):
AttributeError: can't set attribute

  • .. warning:: – A rectangular function must have a strictly positive width:

    >>> Rectangular(1, -1)
Traceback (most recent call last):
ValueError: The width must be strictly positive.
>>> Rectangular(1, 1)
Traceback (most recent call last):
ValueError: The width must be strictly positive.
classmethod from_center_and_width(xc, width, k0=0.0, h=1.0, grid=None)[source]

Initialization of a rectangular function centered in xc, of width a, with an amplitude h and with an initial momentum k0.

Parameters:
  • xc (float) – Center of the rectangular function.
  • width (float) – Width of the rectangular function.
  • k0 (float) – Initial momentum of the rectangular function (default to 0).
  • h (float) – Maximal amplitude of the rectangular function (default to 1.).
  • grid (list or set or numpy array) – Discretization grid (optional).
Returns:

  • Rectangular – An initialized rectangular function.
  • Example
  • >>> r = Rectangular.from_center_and_width(4, 2)
  • >>> r.xl
  • 3.0
  • >>> r.xr
  • 5.0
classmethod from_width_and_center(width, xc, k0=0.0, h=1.0, grid=None)[source]

Similar to the class method from_center_and_width().

Returns:
  • Rectangular – An initialized rectangular function.
  • Example
  • >>> r = Rectangular.from_width_and_center(4, 2)
  • >>> r.xl
  • 0.0
  • >>> r.xr
  • 4.0
xl
Returns:Left border of the rectangular function.
Return type:float
xr
Returns:Right border of the rectangular function.
Return type:float
amplitude
Returns:Amplitude of the rectangular function.
Return type:float
width
Returns:Width of the rectangular function.
Return type:float
center
Returns:Center of the rectangular function.
Return type:float
momentum
Returns:Momentum of the rectangular function.
Return type:float
__eq__(other)[source]
Parameters:object (Another) –

other: object

Returns:
  • bool – True if both objects are Rectangular functions with the same amplitude, width, center and momentum.
  • Examples
  • Two rectangular functions with different amplitudes are
  • different
  • >>> r1 = Rectangular(-4, 2, k0=5, grid=[-1, 0, 1])
  • >>> r2 = Rectangular(-4, 2, k0=5, h=2, grid=[-1, 0, 1])
  • >>> r1 == r2
  • False
  • Two rectangular functions that are identical, except for the
  • grid, are considered to be the same
  • >>> r3 = Rectangular(-4, 2, k0=5, grid=[-1, -0.5, 0, 0.5, 1])
  • >>> r1 == r3
  • True
__add__(other)[source]

Add another function to a rectangular function.

Parameters:other (Function) – Another function.
Returns:
  • Rectangular or Function. – Sum of a rectangular function with another function.
  • Example
  • Two rectangular functions differing only by the amplitude can
  • be added to give another rectangular function
  • >>> r1 = Rectangular(-1, 1)
  • >>> r2 = Rectangular(-1, 1, h=3)
  • >>> r = r1 + r2
  • >>> assert r.amplitude == 4
  • >>> assert r.center == r1.center
  • >>> assert r.width == r1.width
  • >>> assert r.momentum == r1.momentum
  • Two different rectangular functions that were not discretized
  • cannot be added
  • >>> r1 + Rectangular(-2, 2)
  • Traceback (most recent call last)
  • ValueError (Two analytic functions not discretized cannot be added.)
  • Finally, if the rectangular function is not discretized over a
  • grid, but the other function is, then the addition can be
  • performed
  • >>> r = r1 + Function([-1, 0, 1], [1, 2, 3])
  • >>> r.grid
  • array([-1, 0, 1])
  • >>> r.values
  • array([ 2.+0.j, 3.+0.j, 4.+0.j])
is_even
Returns:
  • bool – True if the rectangular function is even.
  • Examples
  • A centered rectangular function is even, even if t grid is
  • not centered
  • >>> Rectangular(-2, 2, grid=[-2, -1, 0]).is_even
  • True
  • A non-centered rectangular function cannot be even
  • >>> Rectangular(-2, 0).is_even
  • False
  • A centered rectangular function with an initial momentum
  • cannot be even
  • >>> Rectangular(-2, 2, k0=1).is_even
  • False
is_odd
Returns:False, as a rectangular function can’t be odd.
Return type:bool
_compute_values(grid)[source]

Evaluation of the Rectangular function for each grid point.

Parameters:grid (numpy array) – Discretization grid.
Returns:
  • float – Value of the Rectangular function over the grid.
  • Examples
  • >>> r = Rectangular(-5, 1, h=-3.5)
  • >>> r.evaluate(-1) == -3.5
  • True
  • >>> r.evaluate(-10) == 0
  • True
abs()[source]
Returns:
  • Rectangular – Absolute value of the Rectangular function.
  • Example
  • The absolute value of a Rectangular function is nothing but
  • the same Rectangular function without initial momentum
  • >>> r = Rectangular(-5, 1, h=4, k0=-6)
  • >>> assert r.abs() == Rectangular(-5, 1, h=4)
conjugate()[source]
Returns:
  • Rectangular – Conjugate of the Rectangular function.
  • Example
  • The conjugate of a Rectangular is the same Rectangular
  • function with a negative momentum
  • >>> r = Rectangular(-5, 1, h=4, k0=-6)
  • >>> assert r.conjugate() == Rectangular(-5, 1, h=4, k0=6)
norm()[source]
Returns:
  • float – Analytic norm of a rectangular function, that is equal to its width times its amplitude squared.
  • Examples
  • >>> r = Rectangular(-1, 1, h=3)
  • >>> r.norm()
  • 18
  • The norm does not depend on the discretization grid
  • >>> r.norm() == Rectangular(-1, 1, h=3, grid=[-1, 0, 1]).norm()
  • True
split(sw_pot)[source]

Split the rectangular function into three other rectangular functions, each one spreading over only one of the three regions defined by a 1D Square-Well potential SWP. If the original rectangular function does not spread over one particular region, the returned value for this region is None.

Parameters:sw_pot (SWPotential) – 1D Square-Well Potential
Returns:Three rectangular functions.
Return type:tuple of length 3
Raises:TypeError – If sw_pot is not a SWPotential instance.
class siegpy.functions.Gaussian(sigma, xc, k0=0.0, h=1.0, grid=None)[source]

Bases: siegpy.functions.AnalyticFunction

A Gaussian function is characterized by:

  • a width sigma
  • a center xc
  • an initial momentum k0
  • an amplitude h

In addition to the behaviour of an analytic function:

  • the norm is computed analytically,
  • the attribute is_even returns True if the Gaussian function is centered, even if the discretization grid is not centered,
  • the equality and addition of two Gaussian functions are also defined.
Parameters:
  • sigma (strictly positive float) – Width of the Gaussian function.
  • xc (float) – Center of the Gaussian function.
  • k0 (float) – Initial momentum of the Gaussian function (default to 0).
  • h (float) – Maximal amplitude of the Gaussian function (default to 1).
  • grid (list or set or numpy array) – Discretization grid (optional).
Raises:

  • ValueError – If sigma is negative.

  • Examples

  • A Gaussian function is characterized by various attributes:

  • >>> g = Gaussian(4, 2, k0=5)

  • >>> g.sigma

  • 4

  • >>> g.center

  • 2

  • >>> g.momentum

  • 5

  • >>> g.amplitude

  • 1.0

  • If no discretization grid is passed, then the atrributes

  • grid and

  • values are set to

  • None:

  • >>> g.grid is None and g.values is None

  • True

  • If a grid is given, the Gaussian is discretized:

  • >>> g1 = Gaussian(4, 2, k0=5, grid=[-1, 0, 1])

  • >>> g2 = Gaussian(4, 2, k0=5, h=2, grid=[-1, 0, 1])

  • >>> np.array_equal(g2.values, 2*g1.values)

  • True

  • .. note:: – The only way to modify the values of a Gaussian is by setting its grid:

    >>> g.grid = [-1, 0, 1]
>>> assert np.array_equal(g.grid, g1.grid)
>>> assert np.array_equal(g.values, g1.values)
>>> g.values = [2, 1, 2]
Traceback (most recent call last):
AttributeError: can't set attribute

  • .. warning:: – Finally, a Gaussian function must have a strictly positive sigma:

    >>> Gaussian(-1, 1)
Traceback (most recent call last):
ValueError: The Gaussian must have a strictly positive sigma.
>>> Gaussian(0, 1)
Traceback (most recent call last):
ValueError: The Gaussian must have a strictly positive sigma.
sigma
Returns:Width of the Gaussian function.
Return type:float
center
Returns:Center of the Gaussian function.
Return type:float
momentum
Returns:Momentum of the Gaussian function.
Return type:float
amplitude
Returns:Amplitude of the Gaussian function.
Return type:float
_params

Shortcut to get the main parameters of a Gaussian function.

Returns:sigma, center and amplitude of the Gaussian function.
Return type:tuple
__eq__(other)[source]
Parameters:other (object) – Another object.
Returns:
  • bool – True if both Gaussian functions have the same sigma, center, momentum and amplitude.
  • Examples
  • Two Gaussian functions with different amplitudes are different
  • >>> g1 = Gaussian(4, 2, k0=5, grid=[-1, 0, 1])
  • >>> g2 = Gaussian(4, 2, k0=5, h=2, grid=[-1, 0, 1])
  • >>> g1 == g2
  • False
  • If only the grid differs, then the two Gaussian functions are
  • the same
  • >>> g3 = Gaussian(4, 2, k0=5, grid=[-1, -0.5, 0, 0.5, 1])
  • >>> g1 == g3
  • True
__add__(other)[source]

Add another function to a Gaussian function.

Parameters:other (Function) – Another function.
Returns:
  • Gaussian or Function. – Sum of a Gaussian function with another function.
  • Example
  • Two Gaussian functions differing only by the amplitude can be
  • added to give another Gaussian function
  • >>> g1 = Gaussian(1, 0)
  • >>> g2 = Gaussian(1, 0, h=3)
  • >>> g = g1 + g2
  • >>> assert g.amplitude == 4
  • >>> assert g.center == g1.center
  • >>> assert g.sigma == g1.sigma
  • >>> assert g.momentum == g1.momentum
  • Two different Gaussian functions that were not discretized
  • cannot be added
  • >>> g1 + Gaussian(1, 1)
  • Traceback (most recent call last)
  • ValueError (Two analytic functions not discretized cannot be added.)
  • Finally, if the Gaussian function is not discretized over a
  • grid, but the other function is, then the addition can be
  • performed
  • >>> g = g1 + Function([-1, 0, 1], [1, 2, 3])
  • >>> g.grid
  • array([-1, 0, 1])
  • >>> g.values
  • array([ 1.60653066+0.j, 3.00000000+0.j, 3.60653066+0.j])
is_even
Returns:
  • bool – True if the Gaussian function is even.
  • Examples
  • A centered Gaussian with no initial momentum is even, even if
  • its grid is not centered
  • >>> Gaussian(2, 0, grid=[-2, -1, 0]).is_even
  • True
  • A non-centered Gaussian is not even
  • >>> Gaussian(2, 2).is_even
  • False
  • A centered Gaussian with a non-zero initial momentum is
  • not even
  • >>> Gaussian(2, 0, k0=1).is_even
  • False
is_odd
Returns:False, as a Gaussian function can’t be odd.
Return type:bool
is_inside(sw_pot, tol=1e-05)[source]

Check if the Gaussian function can be considered as inside the 1D Square-Well potential, given a tolerance value that must be larger than the values of the Gaussian function at the border of the potential.

Parameters:
  • sw_pot (SWPotential) – 1D potential.
  • tol (float) – Tolerance value (default to \(10^{-5}\)).
Returns:

True if the Gaussian function is inside the 1D SWP.
Return type:

bool
Raises:

TypeError – If sw_pot is not a SWPotential instance.
abs()[source]
Returns:
  • Gaussian – Absolute value of the Gaussian function.
  • Example
  • The absolute value of a Gaussian function is nothing but
  • the same Gaussian function without initial momentum
  • >>> g = Gaussian(5, -1, h=4, k0=-6)
  • >>> assert g.abs() == Gaussian(5, -1, h=4)
conjugate()[source]
Returns:
  • Gaussian – Conjugate of the Gaussian function.
  • Example
  • The conjugate of a Gaussian is the same Gaussian function
  • with a negative momentum
  • >>> g = Gaussian(5, -1, h=4, k0=-6)
  • >>> assert g.conjugate() == Gaussian(5, -1, h=4, k0=6)
norm()[source]
Returns:
  • float – Analytic norm of the Gaussian function.
  • Example
  • The norm of a Gaussian function does not depend on the
  • discretization grid
  • >>> g1 = Gaussian(2, 0)
  • >>> g2 = Gaussian(2, 0, grid=[-1, 0, 1])
  • >>> assert g1.norm() == g2.norm()
_compute_values(grid)[source]

Evaluate the Gaussian for each grid point \(x_0\): \(a e^{-\frac{(x_0-xc)^2}{2 sigma^2}} * e^{i k_0 x}\)

Parameters:grid (numpy array) – Discretization grid.
Returns:
  • float or complex – Value of the Gaussian function over the grid.
  • Example
  • >>> g = Gaussian(5, -1, h=-3.5)
  • >>> g.evaluate(-1) == -3.5
  • True