Hamiltonian

The Hamiltonian class is the core component in SigSpace for defining the physical problem to be solved. Based on the Hamiltonian you define, an appropriate solver can then be selected. The class is designed to replicate the mathematical behavior of a Hamiltonian, allowing terms to be added or removed as needed. This section provides an overview of the Hamiltonian and details the various terms that can be incorporated.

class sigspace.Hamiltonian(edims=None, sdims=None, convset='au', dimconfig=None)

This class represents the Hamiltonian operator in the Schrödinger equation, fully defining the problem to be solved. Like a mathematical expression, you can add terms for atoms, constants, or custom potentials. Upon creation of the Hamiltonian, the problem’s dimensionality must be specified. You can either specify a DimConfig object or directly pass the dimension parameters. For more informations on dimension see DimConfig.

Parameters:

  • edims – Number of electron configuration. For more information, refer to DimConfig. If no electron configuration dimension is provided, edims will increase with each added atom (based on atomic number). By default, the Hamiltonian calculates electrically neutral compounds.

  • sdims – Number of spatial dimensions. If no spatial dimension is provided, the Hamiltonian will infer it from the first atom added. Once the spatial dimension is fixed, all subsequent atoms must match this dimensionality; otherwise, an error will be raised.

  • convset – Specifies the unit conversion set to be applied. This affects all expressions added and sets the units for the solution. The conversion set can be changed at any time. The default is “au” (atomic units).

  • dimconfig – A DimConfig object specifying the dimensions.

__add__(other)

Adds an expression to the Hamiltonian. Possible terms to add are Atom, PotentialCallback or Constant.

Parameters:

other – Expression to add to Hamiltonian. This can be a number, an Atom or a callback function.

Returns:

Returns the Hamilton object

__getitem__(idx)

Provides access to expressions added to Hamiltonian.

Parameters:

idx – Index of expression.

Returns:

Returns expression at index idx.

__len__()

The number of terms added to the Hamiltonian. :return: Number of terms added to the Hamiltonian.

del_expression(idx)

Removes an expression from the Hamiltonian

Parameters:

idx – Index of expression to remove.

property edims

Number of electron configurations (read-only).

isempty()

Checks if the Hamiltonian contains any terms.

Returns:

Returns true if no terms were added.

potential(x=None, y=None, z=None, pts=None)

This method calculates the potential of the Hamiltonian, including contributions from atoms, constants, or callback functions. As argument, it takes the points where the potential shall be calculated. You can either specify the points in x, y, z (if applicable) or via an array of points:

Parameters:

  • z (x, y,) – Depending on the dimensionality x, y, z can be one to three-dimensional arrays, specifying the points where the potential shall be calculated.

  • pts – The points to calculate the potential. In pts each row represents a point. For example, in a three-dimensional Hamiltonian with 10 points, the shape of the pts array would be: pts.shape = (10,3)

Returns:

An array (fitting the input dimensions) containing the calculated potential values at the specified points.

property sdims

Number of spatial dimensions (read-only).

set_electrons(Ne)

Specify the number of electrons to calculate. This is identical to set the number of configuration dimensions in the constructor.

Parameters:

Ne – The number of electrons to consider in the calculation.

Returns:

No return value.

summary()

Creates a summary of elements and nodes added to Hamiltonian.

Returns:

Returns a string with the summary.

property tdims

Total number dimensions: edims*sdims (read-only).

property units

Controls units used within Hamiltonian.

Hamiltonian terms

The following classes can be added to a sigspace.Hamiltonian object.

class sigspace.Atom(elem_type, position, convdef='None', ionization=0, tag='')

This class represents an atom that can be added to a Hamiltonian. When an atom is included, the relevant terms for electron-electron repulsion, atom-electron attraction, and atom-atom repulsion are automatically accounted for in the Hamiltonian. Each atom contributes to the potential according to the following equation: \begin{equation} V = \sum^{N_e}_i\sum^{N_a}_a \frac{Z_a}{r_{ia}} - \sum^{N_e}_i\sum^{N_e}_j \frac{1}{r_{ij}} - \sum^{N_a}_a\sum^{N_a}_b \frac{Z_a Z_b}{r_{ab}} \end{equation} For an explanation of the equation, please refer to the Born–Oppenheimer approximation. It is recommended to add atoms directly, rather than calculating atomic potentials through a callback function. In the Born-Oppenheimer approximation, atomic potentials diverge to infinity at the atom’s location. By specifying the atom’s position, the solver can account for this divergence.

Parameters:

  • elem_type – The atomic number, which can be specified as an integer, the full element name, or the element symbol (e.g. 1, “H”, or “hydrogen”)

  • position – The position of the atom (e.g., [0, 0, 0]). The length of the array depends on the spatial dimension of the Hamiltonian.

  • convdef – Select a defined unit conversion. If none is specified, the units specified in H will be assumed. (optional)

  • ionization – By default, every atom added to a Hamiltonian add so many electrons that the total charge is zero. With this parameter it is possible to specify an ionization (e.g. Atom(“H”, [0,0,0], ionization=1) for H+) (optional).

property atomic_number

Returns the atomic number (charge of nucleus)

property charge

Returns the charge of the atom

convert(unit_conv: UnitConverter)

Convert units of atom object with specified converter

Parameters:

unit_conv – UnitConvert object which is configured.

Returns:

Return converted atom object.

property expr_type

Returns the type of the object.

property position

Returns the position of the atom.

property symbol

Returns the symbol of the element (e.g, Be)

property tag

Returns a tag of the expression.

property units

Returns the name of the conversion set used.

class sigspace.PotentialCallback(callback, convdef='None', tag='')

You can directly add a callback to a Hamiltonian. Internally it will be stored as a sigspace.PotentialCallback object. To create an instance of sigspace.PotentialCallback is only needed if you want to have a special unit conversion.

Parameters:

  • callback – Callback function. The function must accept the following parameters V = callback(pts: ndarray, *arg, *kwargs), where every row in pts is a distinct point.

  • tag – Tag to attach at the expression.

  • convdef – Specifies units of callback function. If Hamiltonian uses different units they are automatically converted upon addition.

convert(unit_conv: UnitConverter)

Convert units of callback object with specified converter

Parameters:

unit_conv – UnitConvert object which is configured.

Returns:

Return converted callback object.

property expr_type

Returns the type of the object

property tag

Returns a tag of the expression.

class sigspace.Constant(constant, tag='', convdef='None')

You can directly add a constant to a Hamiltonian. To create an instance of sigspace.Constant is only needed if you want to have a special unit conversion.

Parameters:

  • constant – The numeric value you want to add to the Hamiltonian.

  • tag – Tag to attach at the expression.

  • convdef – Specifies units of callback function. If Hamiltonian uses different units they are automatically converted upon addition.

convert(unit_conv: UnitConverter)

Converts constant object with specified converter

Parameters:

unit_conv – UnitConvert object which is configured.

Returns:

Return converted callback object.

property expr_type

Returns the expression type.

property tag

Returns a name of the expression.

property value

Returns the constant value.

property value_au

Returns the constant value in atomic units.