netket.hilbert.Spin#
- class netket.hilbert.Spin[source]#
Bases:
HomogeneousHilbertHilbert space obtained as tensor product of local spin states.
The correspondance between basis elements of the hilbert space and the configurations that are then fed to variational states is as follows:
State
Old Behavior
inverted_ordering=TrueNew Behavior
inverted_ordering=False↑ ↑ ↑
-1 -1 -1
+1 +1 +1
↑ ↑ ↓
-1 -1 +1
+1 +1 -1
↑ ↓ ↑
-1 +1 -1
+1 -1 +1
↑ ↓ ↓
-1 +1 +1
+1 -1 -1
↓ ↑ ↑
+1 -1 -1
-1 +1 +1
↓ ↑ ↓
+1 -1 +1
-1 +1 -1
↓ ↓ ↑
+1 +1 -1
-1 -1 +1
↓ ↓ ↓
+1 +1 +1
-1 -1 -1
The old behaviour is the default behaviour of NetKet 3.14 and before, while the new behaviour will become the default starting 1st january 2025. For that reason, in the transition period, we will print warnings asking to explicitly specify which ordering you want
Warning
The ordering of the Spin Hilbert space basis has historically always been such that -1=↑, 1=↓, but it will be changed 1st january 2025 to be such that 1=↑, -1=↓.
- The change will break:
code that relies on the assumption that -1=↑;
all saves because the inputs to the network will change;
custom operators that rely on the basis being ordered;
To avoid distruption, NetKet will support both conventions in the (near) future. You can specify the ordering you need with
inverted_ordering = True(historical ordering) orinverted_ordering=False(future default behaviour).If you do not specify this flag, a future version of NetKet might break your serialized weights or other logic, so we strongly reccomend that you either limit yourself to NetKet 3.14, or that you specify
inverted_orderingexplicitly.- Inheritance
- __init__(s, N=1, *, total_sz=None, constraint=None, inverted_ordering=False)[source]#
Hilbert space obtained as tensor product of local spin states.
Note
Since NetKet 3.16 (January 2025) the default ordering of the Spin Hilbert space basis has changed. The new default is such that 1=↑, -1=↓. This change can be controlled by the inverted_ordering flag. If you do not specify this flag, you will get the new behaviour.
To ensure that the old behaviour is maintained, you should specify inverted_ordering=True. If you want to opt into the new default you should specify inverted_ordering=False.
- Parameters:
s (
float) – Spin at each site. Must be integer or half-integer.N (
int) – Number of sites (default=1)total_sz (
float|None) – If given, constrains the total spin of system to a particular value.constraint (
DiscreteHilbertConstraint|None) – A custom constraint on the allowed configurations. This argument cannot be specified at the same time astotal_sz. The constraint must be a subclass ofDiscreteHilbertConstraint.inverted_ordering (
bool) – Flag to specify the ordering of the Local basis. Historically NetKet has always used the convention -1=↑, 1=↓ (corresponding toinverted_ordering=True, but we will change it to 1=↑, -1=↓ (inverted_ordering=False). The default as of September 2024 (NetKet 3.14) isinverted_ordering=True, but we will change it in the near future. The change will (i) break code that relies on the assumption that -1=↑, and (ii) will break all saves because the inputs to the network will change.
Examples
Simple spin hilbert space.
>>> import netket as nk >>> hi = nk.hilbert.Spin(s=1/2, N=4) >>> print(hi.size) 4
- Attributes
- constrained#
The hilbert space does not contain 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.
Typically, objects defined in the constrained space cannot be converted to QuTiP or other formats.
- constraint#
The constraint inflicted upon this poor Hilbert space.
Instead of all possible combinations of local states, only those satisfying the constraint are part of this Hilbert space.
- is_finite#
Whether the local hilbert space is finite.
- is_indexable#
Whether the space can be indexed with an integer
- local_size#
Size of the local degrees of freedom that make the total hilbert space.
- local_states#
A list of discrete local quantum numbers. If the local states are infinitely many, None is returned.
- n_states#
The total dimension of the many-body Hilbert space. Throws an exception iff the space is not indexable.
- shape#
The size of the hilbert space on every site.
- size#
The total number number of degrees of freedom.
- Methods
- all_states()[source]#
Returns all valid states of the Hilbert space.
Throws an exception if the space is not indexable.
- Return type:
- Returns:
A (n_states x size) batch of states. this corresponds to the pre-allocated array if it was passed.
- local_indices_to_states(x, dtype=None)[source]#
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.
- numbers_to_states(numbers)[source]#
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.
- Parameters:
numbers (
numpy.array) – Batch of input numbers to be converted into arrays of quantum numbers.- Return type:
- ptrace(sites)[source]#
Returns the hilbert space without the selected sites.
Not all hilbert spaces support this operation.
- random_state(key=None, size=None, dtype=None)[source]#
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.- Parameters:
key (
Any) – rng state from a jax-style functional generator.size (
int|None) – 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:
- Returns:
A state or batch of states sampled from the uniform distribution on the hilbert space.
Example
>>> import netket, jax >>> hi = netket.hilbert.Qubit(N=2) >>> k1, k2 = jax.random.split(jax.random.PRNGKey(1)) >>> print(hi.random_state(key=k1)) [0 0] >>> print(hi.random_state(key=k2, size=2)) [[0 0] [0 0]]
- states()[source]#
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.
- states_at_index(i)[source]#
A list of discrete local quantum numbers at the site i.
If the local states are infinitely many, None is returned.
- Parameters:
i (
int) – The index of the desired site.- Returns:
A list of values or None if there are infinitely many.
- states_to_local_indices(x)[source]#
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.
Warning
This function is experimental. Use at your own risk.