qlinks.builders package

Submodules

qlinks.builders.optimized_sparse module

class qlinks.builders.optimized_sparse.OptimizedSparseBuildStats(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz, n_scratch_arrays)

Bases: object

Counters collected by OptimizedSparseHamiltonianBuilder.

n_basis

Number of basis states.

Type:

int

n_terms

Number of local update/diagonal operators.

Type:

int

n_raw_actions

Number of raw local actions evaluated.

Type:

int

n_kept_actions

Number of nonzero actions inserted into the matrix.

Type:

int

n_missing_actions

Number of actions whose target state was outside the basis.

Type:

int

nnz

Number of stored nonzero entries after sparse assembly.

Type:

int

n_scratch_arrays

Number of reusable scratch arrays allocated by the builder.

Type:

int

n_basis: int

n_terms: int

n_raw_actions: int

n_kept_actions: int

n_missing_actions: int

nnz: int

n_scratch_arrays: int

__init__(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz, n_scratch_arrays)

class qlinks.builders.optimized_sparse.OptimizedSparseBuildResult(matrix, stats)

Bases: object

Optimized sparse matrix together with build statistics.

matrix

Built sparse matrix.

Type:

Any

stats

Counters describing the optimized build.

Type:

qlinks.builders.optimized_sparse.OptimizedSparseBuildStats

matrix: Any

stats: OptimizedSparseBuildStats

__init__(matrix, stats)

class qlinks.builders.optimized_sparse.OptimizedSparseHamiltonianBuilder(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Bases: object

Sparse builder for update-style local operators.

Operators return compact local updates rather than full output configurations. The builder owns a reusable scratch configuration and inserts H[row, col] += coefficient after applying each update to the current column configuration.

dtype

Matrix dtype.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for actions outside the basis.

Type:

Literal[‘skip’, ‘raise’]

drop_zero_atol

Absolute threshold for dropping small coefficients.

Type:

float

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

on_missing: Literal['skip', 'raise']

drop_zero_atol: float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

build(basis, operators)

build_with_stats(basis, operators)

__init__(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

qlinks.builders.optimized_sparse.build_optimized_sparse_hamiltonian(basis, operators, *, dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Build a sparse Hamiltonian using update-style operators.

Parameters:

• basis (Basis) – Basis that fixes the matrix row/column order.

• operators (Sequence[LocalUpdateOperator | DiagonalLocalOperator]) – Operators supporting diagonal_value or apply_update.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for actions outside the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

Returns:

Sparse Hamiltonian matrix.

Return type:

Any

qlinks.builders.sparse module

class qlinks.builders.sparse.SparseBuildStats(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz)

Bases: object

Counters collected while building a sparse matrix.

n_basis

Number of basis states.

Type:

int

n_terms

Number of local operators.

Type:

int

n_raw_actions

Number of raw operator actions evaluated.

Type:

int

n_kept_actions

Number of nonzero actions inserted into the matrix.

Type:

int

n_missing_actions

Number of actions whose target state was outside the basis.

Type:

int

nnz

Number of stored nonzero entries after duplicate summation.

Type:

int

n_basis: int

n_terms: int

n_raw_actions: int

n_kept_actions: int

n_missing_actions: int

nnz: int

__init__(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz)

class qlinks.builders.sparse.SparseBuildResult(matrix, stats)

Bases: object

Sparse matrix together with build statistics.

matrix

Built sparse matrix.

Type:

Any

stats

Counters describing the build.

Type:

qlinks.builders.sparse.SparseBuildStats

matrix: Any

stats: SparseBuildStats

__init__(matrix, stats)

class qlinks.builders.sparse.SparseHamiltonianBuilder(dtype=<class 'numpy.complex128'>, on_missing='skip', combine_duplicates=True, drop_zero_atol=0.0, backend='scipy')

Bases: object

Generic sparse builder for configuration-space local operators.

The builder applies each operator to each basis configuration and inserts the resulting matrix element H[row, col]. It is the most general builder and works with any LocalOperator, at the cost of allocating full target configurations for non-diagonal actions.

dtype

Matrix dtype.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for actions outside the basis. "skip" drops them; "raise" turns them into a KeyError.

Type:

Literal[‘skip’, ‘raise’]

combine_duplicates

Whether to combine multiple actions from the same column to the same target before insertion.

Type:

bool

drop_zero_atol

Absolute threshold for dropping small coefficients.

Type:

float

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

on_missing: Literal['skip', 'raise']

combine_duplicates: bool

drop_zero_atol: float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

build(basis, operators)

build_with_stats(basis, operators)

__init__(dtype=<class 'numpy.complex128'>, on_missing='skip', combine_duplicates=True, drop_zero_atol=0.0, backend='scipy')

qlinks.builders.sparse.build_sparse_hamiltonian(basis, operators, *, dtype=<class 'numpy.complex128'>, on_missing='skip', combine_duplicates=True, drop_zero_atol=0.0, backend='scipy')

Build a sparse Hamiltonian from local operators.

Parameters:

• basis (Basis) – Basis that fixes the matrix row/column order.

• operators (Sequence[LocalOperator]) – Local operators to sum.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for actions outside the basis.

• combine_duplicates (bool) – Whether to combine duplicate column actions before inserting them.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

Returns:

Sparse Hamiltonian matrix.

Return type:

Any

qlinks.builders.sparse.is_hermitian_sparse(matrix, *, atol=1e-12, backend='auto')

Return whether a sparse matrix is Hermitian within tolerance.

Parameters:

• matrix (Any) – Sparse matrix to test.

• atol (float) – Absolute tolerance for the largest entry of A - A.conjugate().T.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend used to inspect matrix data.

Returns:

True if the matrix is numerically Hermitian.

Return type:

bool

Module contents

class qlinks.builders.OptimizedSparseBuildResult(matrix, stats)

Bases: object

Optimized sparse matrix together with build statistics.

matrix

Built sparse matrix.

Type:

Any

stats

Counters describing the optimized build.

Type:

qlinks.builders.optimized_sparse.OptimizedSparseBuildStats

matrix: Any

stats: OptimizedSparseBuildStats

__init__(matrix, stats)

class qlinks.builders.OptimizedSparseBuildStats(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz, n_scratch_arrays)

Bases: object

Counters collected by OptimizedSparseHamiltonianBuilder.

n_basis

Number of basis states.

Type:

int

n_terms

Number of local update/diagonal operators.

Type:

int

n_raw_actions

Number of raw local actions evaluated.

Type:

int

n_kept_actions

Number of nonzero actions inserted into the matrix.

Type:

int

n_missing_actions

Number of actions whose target state was outside the basis.

Type:

int

nnz

Number of stored nonzero entries after sparse assembly.

Type:

int

n_scratch_arrays

Number of reusable scratch arrays allocated by the builder.

Type:

int

n_basis: int

n_terms: int

n_raw_actions: int

n_kept_actions: int

n_missing_actions: int

nnz: int

n_scratch_arrays: int

__init__(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz, n_scratch_arrays)

class qlinks.builders.OptimizedSparseHamiltonianBuilder(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Bases: object

Sparse builder for update-style local operators.

Operators return compact local updates rather than full output configurations. The builder owns a reusable scratch configuration and inserts H[row, col] += coefficient after applying each update to the current column configuration.

dtype

Matrix dtype.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for actions outside the basis.

Type:

Literal[‘skip’, ‘raise’]

drop_zero_atol

Absolute threshold for dropping small coefficients.

Type:

float

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

on_missing: Literal['skip', 'raise']

drop_zero_atol: float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

build(basis, operators)

build_with_stats(basis, operators)

__init__(dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

class qlinks.builders.SparseBuildResult(matrix, stats)

Bases: object

Sparse matrix together with build statistics.

matrix

Built sparse matrix.

Type:

Any

stats

Counters describing the build.

Type:

qlinks.builders.sparse.SparseBuildStats

matrix: Any

stats: SparseBuildStats

__init__(matrix, stats)

class qlinks.builders.SparseBuildStats(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz)

Bases: object

Counters collected while building a sparse matrix.

n_basis

Number of basis states.

Type:

int

n_terms

Number of local operators.

Type:

int

n_raw_actions

Number of raw operator actions evaluated.

Type:

int

n_kept_actions

Number of nonzero actions inserted into the matrix.

Type:

int

n_missing_actions

Number of actions whose target state was outside the basis.

Type:

int

nnz

Number of stored nonzero entries after duplicate summation.

Type:

int

n_basis: int

n_terms: int

n_raw_actions: int

n_kept_actions: int

n_missing_actions: int

nnz: int

__init__(n_basis, n_terms, n_raw_actions, n_kept_actions, n_missing_actions, nnz)

class qlinks.builders.SparseHamiltonianBuilder(dtype=<class 'numpy.complex128'>, on_missing='skip', combine_duplicates=True, drop_zero_atol=0.0, backend='scipy')

Bases: object

Generic sparse builder for configuration-space local operators.

The builder applies each operator to each basis configuration and inserts the resulting matrix element H[row, col]. It is the most general builder and works with any LocalOperator, at the cost of allocating full target configurations for non-diagonal actions.

dtype

Matrix dtype.

Type:

type[Any] | numpy.dtype[Any] | numpy._typing._dtype_like._SupportsDType[numpy.dtype[Any]] | tuple[Any, Any] | list[Any] | numpy._typing._dtype_like._DTypeDict | str | None

on_missing

Policy for actions outside the basis. "skip" drops them; "raise" turns them into a KeyError.

Type:

Literal[‘skip’, ‘raise’]

combine_duplicates

Whether to combine multiple actions from the same column to the same target before insertion.

Type:

bool

drop_zero_atol

Absolute threshold for dropping small coefficients.

Type:

float

backend

Sparse backend name or backend object.

Type:

Literal[‘scipy’, ‘cupy’, ‘auto’] | qlinks.backends.sparse.SparseBackend

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None

on_missing: Literal['skip', 'raise']

combine_duplicates: bool

drop_zero_atol: float

backend: Literal['scipy', 'cupy', 'auto'] | SparseBackend

build(basis, operators)

build_with_stats(basis, operators)

__init__(dtype=<class 'numpy.complex128'>, on_missing='skip', combine_duplicates=True, drop_zero_atol=0.0, backend='scipy')

qlinks.builders.build_optimized_sparse_hamiltonian(basis, operators, *, dtype=<class 'numpy.complex128'>, on_missing='skip', drop_zero_atol=0.0, backend='scipy')

Build a sparse Hamiltonian using update-style operators.

Parameters:

• basis (Basis) – Basis that fixes the matrix row/column order.

• operators (Sequence[LocalUpdateOperator | DiagonalLocalOperator]) – Operators supporting diagonal_value or apply_update.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for actions outside the basis.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

Returns:

Sparse Hamiltonian matrix.

Return type:

Any

qlinks.builders.build_sparse_hamiltonian(basis, operators, *, dtype=<class 'numpy.complex128'>, on_missing='skip', combine_duplicates=True, drop_zero_atol=0.0, backend='scipy')

Build a sparse Hamiltonian from local operators.

Parameters:

• basis (Basis) – Basis that fixes the matrix row/column order.

• operators (Sequence[LocalOperator]) – Local operators to sum.

• dtype (type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None) – Matrix dtype.

• on_missing (Literal['skip', 'raise']) – Policy for actions outside the basis.

• combine_duplicates (bool) – Whether to combine duplicate column actions before inserting them.

• drop_zero_atol (float) – Absolute threshold for dropping small coefficients.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend name or backend object.

Returns:

Sparse Hamiltonian matrix.

Return type:

Any

qlinks.builders.is_hermitian_sparse(matrix, *, atol=1e-12, backend='auto')

Return whether a sparse matrix is Hermitian within tolerance.

Parameters:

• matrix (Any) – Sparse matrix to test.

• atol (float) – Absolute tolerance for the largest entry of A - A.conjugate().T.

• backend (Literal['scipy', 'cupy', 'auto'] | ~qlinks.backends.sparse.SparseBackend) – Sparse backend used to inspect matrix data.

Returns:

True if the matrix is numerically Hermitian.

Return type:

bool