class netket.experimental.hilbert.SpinOrbitalFermions[source]#

Bases: HomogeneousHilbert

Hilbert space for 2nd quantization fermions with spin s distributed among n_orbital orbitals.

The number of fermions can be fixed globally or fixed on a per spin projection.


This class is simply a convenient wrapper that creates a Fock or TensorHilbert of Fock spaces with occupation numbers 0 or 1. It is mainly useful to avoid needing to specify the n_max=1 each time, and adds convenient functions such as _get_index and _spin_index, which allow one to index the correct TensorHilbert corresponding to the right spin projection.

Inheritance diagram of netket.experimental.hilbert.SpinOrbitalFermions
__init__(n_orbitals, s=None, *, n_fermions=None, n_fermions_per_spin=None)[source]#

Constructs the hilbert space for spin-s fermions on n_orbitals.

Samples of this hilbert space represent occupation numbers \((0,1)\) of the orbitals. The number of fermions may be fixed to n_fermions. If the spin is different from 0 or None, n_fermions can also be a list to fix the number of fermions per spin component. Using this class, one can generate a tensor product of fermionic hilbert spaces that distinguish particles with different spin.

  • n_orbitals (int) – number of orbitals we store occupation numbers for. If the number of fermions per spin is conserved, the different spin configurations are not counted as orbitals and are handled differently.

  • s (Optional[float]) – spin of the fermions.

  • n_fermions (Optional[int]) – (optional) fixed number of fermions per spin (conserved). If specified, the total number of fermions is conserved. If the fermions have a spin, the number of fermions per spin subsector is not conserved.

  • n_fermions_per_spin (Optional[tuple[int, ...]]) – (optional) list of the fixed number of fermions for every spin subsector. This automatically enforces a global population constraint. Only one between n_fermions and n_fermions_per_spin can be specified. The length of the iterable should be \(2S+1\).


A SpinOrbitalFermions object


The hilbert space does not contains prod(hilbert.shape) basis states.

Typical constraints are population constraints (such as fixed number of bosons, fixed magnetization…) which ensure that only a subset of the total unconstrained space is populated.


True if the hilbert space can be indexed by a single 32-bit unsigned integer.


Whether the space can be indexed with an integer


Size of the local degrees of freedom that make the total hilbert space.


A list of discrete local quantum numbers. If the local states are infinitely many, None is returned.


The total number of fermions. None if unspecified.


Tuple identifying the per-subsector population constraint.

This tuple has length 1 for spinless fermions and length 2s+1 for spinful fermions. Every element is an integer or None, where None means no constraint on the number of fermions in that subsector.


The number of orbitals (for each spin subsector if relevant).


Total number of spin subsectors. If spin is None, this is 1.


Total size of the hilbert space, if indexable.


The size of the hilbert space on every site.


Size of the hilbert space. In case the fermions have spin s, the size is (2*s+1)*n_orbitals


Returns the spin of the fermions

local_indices_to_states(x, dtype=None)#

Converts a tensor of integers to the corresponding local_values in this hilbert space.

Equivalent to

The input last dimension must match the size of this Hilbert space. This function can be jax-jitted.


x (Union[ndarray, Array]) – a tensor with integer dtype and whose last dimension matches the size of this Hilbert space.


a tensor with the same shape as the input, and values corresponding to the local_state indexed by the input tensor x.


Returns the quantum numbers corresponding to the n-th basis state for input n.

n is an array of integer indices such that numbers[k]=Index(states[k]). Throws an exception iff the space is not indexable.

This function validates the inputs by checking that the numbers provided are smaller than the Hilbert space size, and throws an error if that condition is not met. When called from within a jax.jit context, this uses {func}`equinox.error_if` to throw runtime errors.


numbers (numpy.array) – Batch of input numbers to be converted into arrays of quantum numbers.

Return type:

Union[ndarray, Array]


Returns the hilbert space without the selected sites.

Not all hilbert spaces support this operation.


sites (Union[int, Iterable]) – a site or list of sites to trace away

Return type:



The partially-traced hilbert space. The type of the resulting hilbert space might be different from the starting one.

random_state(key=None, size=None, dtype=<class 'numpy.float32'>)#

Generates either a single or a batch of uniformly distributed random states. Runs as random_state(self, key, size=None, dtype=np.float32) by default.

  • key – rng state from a jax-style functional generator.

  • size (Optional[int]) – If provided, returns a batch of configurations of the form (size, N) if size is an integer or (*size, N) if it is a tuple and where \(N\) is the Hilbert space size. By default, a single random configuration with shape (#,) is returned.

  • dtype – DType of the resulting vector.

Return type:



A state or batch of states sampled from the uniform distribution on the hilbert space.


>>> import netket, jax
>>> hi = netket.hilbert.Qubit(N=2)
>>> k1, k2 = jax.random.split(jax.random.PRNGKey(1))
>>> print(hi.random_state(key=k1))
[1. 0.]
>>> print(hi.random_state(key=k2, size=2))
[[0. 0.]
 [0. 1.]]

Size of the local degrees of freedom for the i-th variable.


i (int) – The index of the desired site

Return type:



The number of degrees of freedom at that site


Returns an iterator over all valid configurations of the Hilbert space. Throws an exception iff the space is not indexable. Iterating over all states with this method is typically inefficient, and `all_states` should be preferred.

Return type:



A list of discrete local quantum numbers at the site i.

If the local states are infinitely many, None is returned.


i (int) – The index of the desired site.


A list of values or None if there are infinitely many.


Returns a tensor with the same shape of x, where all local values are converted to indices in the range 0…self.shape[i]. This function is guaranteed to be jax-jittable.

For the Fock space this returns x, but for other hilbert spaces such as Spin this returns an array of indices.


This function is experimental. Use at your own risk.


x – a tensor containing samples from this hilbert space


a tensor containing integer indices into the local hilbert


Returns the basis state number corresponding to given quantum states.

The states are given in a batch, such that states[k] has shape (hilbert.size). Throws an exception iff the space is not indexable.


states (Union[ndarray, Array]) – Batch of states to be converted into the corresponding integers.


Array of integers corresponding to states.

Return type: