netket_foundation.expectation_value.ISState

class netket_foundation.expectation_value.ISState

Bases: object

Importance-sampled view: physical samples drawn from a reference distribution (characterized by log_probs_ref) evaluated at variables under apply_fn.

IS weights are computed once and cached across successive .expect() calls.

Typical construction:

# From a live MCState reference, reweighting to target parameters is_st = ISState.from_mc_state(mc_ref, target_params)

# From a self-contained nqxpack file (state + reference bundled) is_st = ISState.from_nqxpack(“ref.nk”, target_params)

# From lightweight .npz arrays paired with a live target state is_st = vs.is_state(pars, reference=SamplesWithProb.load(“ref.npz”))

# From raw arrays directly is_st = ISState(samples, log_probs, apply_fn, variables)

__init__(samples, log_probs_ref, apply_fn, variables, *, chunk_size=None)

Parameters:

• samples (Array) – Physical configurations, shape (n_samples, N).

• log_probs_ref (Array) – Reference log-density log p_ref(sigma) at each sample, shape (n_samples,).

• apply_fn (Callable) – Model apply function for the target state; signature (variables, x) -> log_amplitude.

• variables (Any) – Variables of the (target) state being evaluated.

• chunk_size (int | None) – Optional chunk size for model evaluation.

Attributes

apply_fn

ess

ess_fraction

n_samples

normalized_weights

IS weights normalized to sum 1.

samples

variables

Methods

expect(observable, *, chunk_size=None)

Compute the IS-weighted expectation value of an observable.

Dispatches on the observable type via nk.vqs.expect. The default overload handles any AbstractOperator via local values. Custom observables (e.g. SusceptibilityObservable) register their own overload with @nk_expect.dispatch.

IS weights are cached after the first call and reused across calls.

Parameters:

chunk_size (int | None)

classmethod from_mc_state(mc_ref, target, *, chunk_size=None)

Build an ISState from an already-sampled MCState reference.

mc_ref supplies both the reference distribution (its samples and log-probabilities) and the model; target selects the parameters that model is evaluated at for the target distribution.

Parameters:

• mc_ref (MCState) – Sampled reference state. Provides the samples and the target model (mc_ref._apply_fun).

• target (Any) – Target foundational parameters (a 1-D array). The target variables reuse mc_ref’s variable tree with only the "foundational" parameters swapped. A full variables dict may be passed instead for a plain MCState reference that has no foundational collection.

• chunk_size (int | None)

Return type:

ISState

classmethod from_nqxpack(path, target, *, key='state', chunk_size=None)

Load a state saved by netket_foundation.vqs.save() and use it as the IS reference, reweighting to the target parameters target.

If the file bundles a reference distribution (SamplesWithProb), its samples and log-probabilities are used directly. Otherwise the reference is reconstructed from the loaded state’s samples (drawing them if the state has not been sampled yet).

Parameters:

• path (str) – Path to the .nk file written by nkf.vqs.save / nqxpack.

• target (Any) – Target foundational parameters (a 1-D array), or a full variables dict for a plain MCState reference.

• key (str) – Key under which the state was stored (default “state”).

• chunk_size (int | None)

Return type:

ISState