pythtb.TBModel.set_onsite#

TBModel.set_onsite(onsite_en, ind_i=None, mode='set')[source]#

Define on-site energies for tight-binding orbitals.

This assigns on-site matrix elements

\[H_{ii}(\mathbf{0}) = \langle \phi_{\mathbf{0}i} | H | \phi_{\mathbf{0}i} \rangle \]

for orbital \(i\) in the home unit cell.

Parameters:
onsite_enfloat, array_like, (2, 2) numpy.ndarray, str, callable

The on-site energy or parameter provider to set.

Added in version 2.0.0: Symbolic expressions and callables for onsite energies.

Valid formats depend on whether spinful is True or False, and whether a single orbital index ind_i is specified or all orbitals are being set at once.

  • Spinless models (spinful=False)

    • Real scalar.

  • Spinful models (spinful=True)

    • Scalar a -> \(a I_2\) (same value for both spins).

    • 4-vector [a, b, c, d] -> \(a I_2 + b \sigma_x + c \sigma_y + d \sigma_z\)

      Explicitly, a 4-vector produces

      \[\begin{split}\begin{pmatrix} a+d & b - i c \\ b + i c & a-d \end{pmatrix}.\end{split}\]

    • 2x2 matrix (Hermitian ndarray).

  • Symbolic definitions

    • String: symbolic expression in user-defined parameters.

    • Callable: f(param) returning any of the above forms.

If ind_i is None, this must be a length-norb sequence of values, one per orbital.

ind_iint, optional

Orbital index to update. If omitted, update all orbitals; in that case onsite_en must be a sequence of length norb.

mode{‘set’, ‘add’}, optional

Operation mode.

  • 'set': replace existing on-site value(s). (Default)

  • 'add': add to existing value(s).

Deprecated since version 2.0.0: mode="reset" is deprecated. Use mode="set" instead.

See also

set_hop

Define hopping amplitudes between orbitals.

set_parameters

Register parameter values

with_parameters

Return a new TBModel with specified parameters.

Notes

  • When mode='add' the new value is added to the existing entry.

  • Symbolic and callable inputs automatically register their parameter names. For callables with multiple parameters, each parameter is registered.

  • Parameter evaluation is scalar only. Spinful on-site blocks must then be set with callables so that the returned values match the expected spinful structure.

    Example:

    # Spinful on-site via 4-vector with one parameter 'mA'
tb.set_onsite(lambda mA: [mA, 0.2, 0.0, -0.1], ind_i=0) 

# Spinful on-site via full 2x2 matrix with two parameters 'mA' and 'mB'
tb.set_onsite(
    lambda mA, mB: np.array([[mA + mB, 0.1 - 0.2j],
                             [0.1 + 0.2j, mA - mB]]),
    ind_i=1
)

    Parameters values must later be supplied as scalars or 1D arrays to methods such as set_parameters(), hamiltonian(), velocity(), solve_ham(), etc., via keyword arguments.

  • Providing parameter values to downstream observables such as hamiltonian(), velocity(), solve_ham(), etc., does not permanently store them in the model; they are used only for that evaluation. To persist parameter values on the model, use set_parameters().

Examples

Set all on-site energies:

>>> tb.set_onsite([0.0, 1.0, 2.0])

Add to a single orbital:

>>> tb.set_onsite(100.0, ind_i=1, mode="add")

Overwrite a single orbital:

>>> tb.set_onsite(0.0, ind_i=1, mode="set")

Spinful on-site via 4-vector:

>>> tb.set_onsite([1.0, 0.2, 0.0, -0.1], ind_i=0)

Symbolic parameter:

>>> tb.set_onsite("mA", ind_i=0)

Callable parameter:

>>> tb.set_onsite(lambda mA: mA**2, ind_i=0)

Callable list over all orbitals with the same parameter but different functional forms:

>>> tb.set_onsite([lambda mA: mA, lambda mA: 2*mA, lambda mA: 3*mA])

Later usage:

>>> H = tb.hamiltonian(k_pts, mA=1.2)
>>> H = tb.hamiltonian(k_pts, mA=np.linspace(0, 2, 5))
On this page