API Reference

The reference below is generated automatically from the public nanokwant API using mkdocstrings.

Hamiltonian Construction

Generate the finite system Hamiltonian in band matrix format.

The diagonal ordered format defined as

ab[u + i - j, j] == a[i,j]

where a is the matrix.

Parameters:

Name	Type	Description	Default
`system`	`HamiltonianType`	Dictionary mapping hopping lengths to term dictionaries.	required
`num_sites`	`int \| None`	Number of sites. Can be None if array parameters are provided.	required
`params`	`dict`	Parameter values (constants, callables, or arrays).	required
`hermitian`	`bool`	If True, expand system to include negative hoppings. Default is True.	`True`
`format`	`str`	Output format: "general" (default) for scipy.linalg.solve_banded, or "eig_banded" for scipy.linalg.eig_banded (only upper bands, hermitian only).	`'general'`
`shrink`	`bool`	Reserved for a future optimization that trims zero bands. The current low-level assembler always returns the full theoretical bandwidth. Passing `shrink=True` raises `NotImplementedError` for now.	`False`

Returns:

Type	Description
`BandedMatrix`	Wrapper around the banded matrix. Use `np.asarray(result)` to obtain the SciPy-compatible array and `result.bandwidth` for `(l, u)`.

Construct the matrix representation of the Hamiltonian.

Mainly used for testing purposes.

Scattering Calculations

Construct the scattering system in banded format.

This function constructs a linear system for scattering calculations with leads attached to a 1D tight-binding system. The leads are defined using the first/last hopping and onsite terms of the system.

Parameters:

Name	Type	Description	Default
`system`	`HamiltonianType`	Dictionary mapping hopping lengths to term dictionaries. Must be in Hermitian format (only non-negative hoppings). Must only contain nearest-neighbor hopping (hop lengths 0 and 1).	required
`num_sites`	`int \| None`	Number of sites in the scattering region.	required
`params`	`dict`	Parameter values (constants, callables, or arrays).	required
`energy`	`float`	Energy at which to compute the scattering problem.	required
`leads`	`(both, left, right)`	Which leads to attach. "both" attaches leads at both ends, "left" only at the beginning, "right" only at the end.	`"both"`

Returns:

Name	Type	Description
`lhs`	`BandedMatrix`	Left-hand side matrix in banded format. Convert to `np.ndarray` for SciPy solvers and access `lhs.bandwidth` to obtain `(l, u)`.
`rhs`	`ndarray`	Right-hand side matrix containing all incoming leads concatenated column-wise. Shape is (total_dof, total_modes).
`modes`	`dict[str, PropagatingModes]`	Mapping from attached lead names to their propagating modes.

Raises:

Type	Description
`ValueError`	If the system contains hoppings longer than nearest-neighbor.
`ValueError`	If the system contains negative hoppings (not in Hermitian format).

Notes

The implementation follows Kwant's approach to constructing scattering systems (see kwant.solvers.common.SparseSolver._make_linear_sys), but constructs the result in banded matrix format for efficiency in 1D systems.

The linear system constructed is similar to Kwant's: We augment the Hamiltonian with blocks for the lead modes, creating:

[[H - E*I,  V†u_out],  [[ψ_scatter], = [[0        ],
 [V,        -λ_out^-1]] [ψ_lead   ]]    [-u_in λ_in^-1]]

where: - H is the scattering region Hamiltonian - V is the coupling to the lead - u_out, u_in are outgoing/incoming mode wave functions - λ_out, λ_in are the outgoing/incoming mode eigenvalues

Compute the scattering matrix for a system with leads.

Parameters:

Name	Type	Description	Default
`system`	`HamiltonianType`	System definition in Hermitian format.	required
`num_sites`	`int \| None`	Number of sites in the scattering region.	required
`params`	`dict`	Parameter values.	required
`energy`	`float`	Energy at which to compute the S-matrix.	required
`leads`	`(both, left, right)`	Which leads to attach.	`"both"`

Returns:

Name	Type	Description
`S`	`ndarray`	Scattering matrix with shape (total_modes, total_modes).