Trait Basis 

pub trait Basis: Send + Sync {
    type State: Copy + Eq + Send + Sync;

    // Required methods
    fn len(&self) -> usize;
    fn state(&self, index: usize) -> Result<Self::State>;
    fn index(&self, state: Self::State) -> Result<usize>;
    fn apply_local(
        &self,
        state: Self::State,
        operator: &str,
        sites: &[usize],
    ) -> Result<Option<(Self::State, Complex64)>>;

    // Provided methods
    fn apply_local_transitions(
        &self,
        state: Self::State,
        operator: &str,
        sites: &[usize],
    ) -> Result<LocalTransitions<Self::State>> { ... }
    fn apply_local_unreduced_transitions(
        &self,
        state: Self::State,
        operator: &str,
        sites: &[usize],
    ) -> Result<LocalTransitions<Self::State>> { ... }
    fn visit_local_unreduced_transitions<F>(
        &self,
        state: Self::State,
        operator: &str,
        sites: &[usize],
        visit: F,
    ) -> Result<()>
       where Self: Sized,
             F: FnMut(Self::State, Complex64) -> Result<()> { ... }
    fn transition_orbit_size(&self, _state: Self::State) -> Result<usize> { ... }
    fn reduction_image(
        &self,
        state: Self::State,
    ) -> Result<Option<ReductionImage<Self::State>>> { ... }
    fn reduce_transition(
        &self,
        state: Self::State,
        source_orbit_size: usize,
    ) -> Result<Option<(Self::State, Complex64)>> { ... }
    fn index_transition(
        &self,
        state: Self::State,
        source_orbit_size: usize,
    ) -> Result<Option<(usize, Complex64)>> { ... }
    fn operator_preserves_particle_sector(
        &self,
        _operator: &str,
    ) -> Result<bool> { ... }
    fn operator_preserves_particle_sector_on_sites(
        &self,
        operator: &str,
        _sites: &[usize],
    ) -> Result<bool> { ... }
    fn is_empty(&self) -> bool { ... }
}

Finite Hilbert-space basis and its local operator semantics.

Required Associated Types

type State: Copy + Eq + Send + Sync

Integer-like state representation used by this basis.

Required Methods

fn len(&self) -> usize

Return the number of vectors in the basis.

fn state(&self, index: usize) -> Result<Self::State>

Return the encoded state at a basis index.

Implementations return QmbedError::StateNotInBasis for an invalid row rather than panicking.

fn index(&self, state: Self::State) -> Result<usize>

Locate an encoded state in the basis.

fn apply_local( &self, state: Self::State, operator: &str, sites: &[usize], ) -> Result<Option<(Self::State, Complex64)>>

Apply one local operator string to one encoded state.

The result is None when the action is exactly zero. Bases whose actions branch override Basis::apply_local_transitions.

Provided Methods

fn apply_local_transitions( &self, state: Self::State, operator: &str, sites: &[usize], ) -> Result<LocalTransitions<Self::State>>

Applies a local operator and returns every nonzero destination.

Most spin-one-half, boson ladder, and fermion strings are deterministic, so the default implementation wraps Basis::apply_local. Higher-spin Cartesian operators and general user-defined local matrices can branch and override this method without changing the universal assembler.

fn apply_local_unreduced_transitions( &self, state: Self::State, operator: &str, sites: &[usize], ) -> Result<LocalTransitions<Self::State>>

Local action before symmetry-sector reduction. Cross-sector builders use this path and let the target basis perform the reduction.

fn visit_local_unreduced_transitions<F>( &self, state: Self::State, operator: &str, sites: &[usize], visit: F, ) -> Result<()>

where Self: Sized, F: FnMut(Self::State, Complex64) -> Result<()>,

Streams unreduced destinations directly to a consumer.

This is the universal hot-path interface used by assemblers. The default covers deterministic bases without constructing an intermediate collection; branching and symmetry-reduced bases override it while preserving the same consumer contract.

fn transition_orbit_size(&self, _state: Self::State) -> Result<usize>

Orbit size of a canonical source state used in projector normalization.

fn reduction_image( &self, state: Self::State, ) -> Result<Option<ReductionImage<Self::State>>>

Return the canonical reduction metadata for a physical state.

Explicit bases use a one-state orbit. Symmetry-reduced bases override this query without exposing their lookup-table representation.

fn reduce_transition( &self, state: Self::State, source_orbit_size: usize, ) -> Result<Option<(Self::State, Complex64)>>

Map an unreduced physical target state into this basis.

fn index_transition( &self, state: Self::State, source_orbit_size: usize, ) -> Result<Option<(usize, Complex64)>>

Reduces a physical target and locates its row in one operation.

Assemblers use this fused boundary to avoid looking up the same state once during reduction and again during indexing.

fn operator_preserves_particle_sector(&self, _operator: &str) -> Result<bool>

Whether a local operator string preserves the particle-sector constraints represented by this basis. Unconstrained and custom bases accept every syntactically valid string by default.

fn operator_preserves_particle_sector_on_sites( &self, operator: &str, _sites: &[usize], ) -> Result<bool>

Site-aware particle-sector check for bases whose local labels encode species as well as position.

Most bases depend only on the operator string and inherit this default. Multi-species bases may override it so a unified orbital convention remains physically meaningful without inserting a species separator.

fn is_empty(&self) -> bool

Return whether the basis contains no vectors.

Implementors

impl Basis for PackedBasis

type State = u128

impl Basis for WidePackedBasis

type State = ErasedState

impl Basis for BosonBasis1D

type State = u128

impl Basis for PackedPhotonBasis

type State = u128

impl Basis for PackedTensorBasis

type State = u128

impl Basis for SpinBasis1D

type State = u128

impl Basis for SpinfulFermionBasis1D

type State = u128

impl Basis for SpinlessFermionBasis1D

type State = u128

impl<Left, Right> Basis for TensorBasis<Left, Right>

where Left: Basis, Right: Basis, Left::State: 'static, Right::State: 'static,

type State = (<Left as Basis>::State, <Right as Basis>::State)

impl<Matter> Basis for PhotonBasis<Matter>

where Matter: Basis, Matter::State: Hash + 'static,

type State = (<Matter as Basis>::State, u128)

impl<Parent> Basis for GeneralBasis<Parent>

where Parent: Basis, Parent::State: Hash + Ord + 'static,

type State = <Parent as Basis>::State

impl<State> Basis for UserBasis<State>

where State: Copy + Eq + Hash + Send + Sync + 'static,

type State = State

impl<const WORDS: usize> Basis for WideSpinBasis<WORDS>

type State = WideState<WORDS>