Gaussian MRFs

Continuous-state EBMs with exact block Gibbs. The energy is quadratic, so the target is a multivariate normal with precision β·P and mean P⁻¹h, and the single-site conditionals are themselves Gaussian — within a color class they are independent scalar Gaussians, so no linear solve is needed anywhere.

Positive definiteness of P is the caller's responsibility; strict diagonal dominance is a simple sufficient condition. All interaction arrays are linear in β, so NRPT's temperature-linear template mode applies bit-exactly.

Because an unbounded state space has no proper β = 0 member, GaussianEBM reports proper_at_beta_zero = False and nrpt rejects a ladder starting at exactly β = 0. Either use beta_range=(β_min > 0, 1.0), or anneal from a proper reference with AnnealedEBM.

hamon.models.GaussianEBM

A Gaussian Markov random field:

\[\mathcal{E}(x) = \beta \left( \tfrac{1}{2} \sum_i d_i x_i^2 - \sum_i h_i x_i + \sum_{(i,j)} c_{ij} x_i x_j \right)\]

i.e. x ~ N(P⁻¹h, (βP)⁻¹) with P_ii = d_i and P_ij = c_ij.

Attributes:

• nodes: the :class:~hamon.pgm.GaussianNode\ s.
• edges: (node, node) pairs carrying the off-diagonal couplings; each undirected pair appears once.
• diag: per-node precision diagonal d (must make P positive definite; strict diagonal dominance suffices).
• lin: per-node linear term h.
• couplings: per-edge off-diagonal precision c.
• beta: scalar inverse temperature.

nodes and edges are identity-hashed sequences shared across with_beta copies, keeping the jit caches hitting (same convention as :class:~hamon.models.IsingEBM). See the module docstring for why proper_at_beta_zero is False.

__init__(nodes, edges, diag: Array, lin: Array, couplings: Array, beta)

hamon.models.GaussianSamplingProgram

Thin wrapper specializing :class:ModelSamplingProgram to a GMRF.

__init__(ebm: GaussianEBM, free_blocks: list, clamped_blocks: list[hamon.block_management.Block], *, _gibbs_spec: hamon.block_sampling.BlockGibbsSpec | None = None)

hamon.models.gaussian_init(key: Key[Array, ''], model: GaussianEBM, blocks: list[hamon.block_management.Block], batch_shape: tuple[int, ...] = ()) -> list[Array]

Draw an initial state from the site-independent part of the model.

Samples each node from N(h_i/d_i, 1/(β·d_i)) — the model with couplings ignored. The continuous counterpart of hinton_init: not the target distribution, just a sensibly-scaled starting point for Gibbs/NRPT. Requires β > 0 (the β = 0 member is improper; see GaussianEBM.proper_at_beta_zero).

hamon.models.GaussianGibbsConditional

Exact Gaussian Gibbs update for continuous nodes.

Accumulates the conditional's natural parameters from quadratic interactions —

\[\text{prec}_i = \sum \text{diag}_i, \qquad \eta_i = \sum \text{lin}_i - \sum \text{coupling}_{ij}\, x_j\]

— and draws x_i ~ N(η_i / prec_i, 1 / prec_i). Interaction arrays are premasked at program construction (padded entries zeroed), so plain sums over the multiplicity axis are correct, exactly as in the discrete conditionals. Every head node must carry at least one :class:QuadraticSelfInteraction with positive diag — otherwise its conditional precision is zero (an improper flat conditional) and the draw produces non-finite values.

n_keys class-attribute

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

int('0b100', base=0) 4

__abstractclassvars__ class-attribute

Build an immutable unordered collection of unique elements.

__abstractmethods__ class-attribute

Build an immutable unordered collection of unique elements.

__abstractvars__ class-attribute

Build an immutable unordered collection of unique elements.

__annotations__ class-attribute

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_fields__ class-attribute

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_params__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__firstlineno__ class-attribute

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

int('0b100', base=0) 4

__match_args__ class-attribute

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__static_attributes__ class-attribute

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

init() -> None

Initialize the sampler state before sampling begins.

This is called before the first iteration of block sampling, after which the return of this method is superseded by the return from sample.

Returns:

Type	Description
None	the initial sampler state to use for the first iteration of block sampling.

sample(key: Key, interactions: list[PyTree], active_flags: list[Array], states: list[list[PyTree[Shaped[Array, 'nodes ?*state'], State]]], sampler_state: ~_SamplerState, output_sd: PyTree[jax.ShapeDtypeStruct]) -> tuple[PyTree[Shaped[Array, 'nodes ?*state'], State], ~_SamplerState]

Sample from the distribution by first computing the parameters and then generating a sample based off of them.

key is either a single key — split here, as before — or the n_keys-long stack the block runner batch-split on this sampler's behalf. The two are the same keys either way.

__init__() -> None

Initialize self. See help(type(self)) for accurate signature.

compute_parameters(key: Key, interactions: list[PyTree], active_flags: list[Array], states: list[list[PyTree[Shaped[Array, 'nodes ?*state'], _State]]], sampler_state: None, output_sd: PyTree[jax.ShapeDtypeStruct]) -> PyTree

sample_given_parameters(key: Key, parameters: PyTree, sampler_state: None, output_sd: PyTree[jax.ShapeDtypeStruct]) -> tuple[PyTree[Shaped[Array, 'nodes ?*state'], _State], None]

Factors and interactions

hamon.models.QuadraticSelfInteraction

Per-node quadratic + linear energy terms ½·diag·x² − lin·x.

Attributes:

• diag: coefficient of ½ x² per head node (the precision diagonal, already scaled by β). Must be positive for the conditional to be proper.
• lin: coefficient of x per head node (the linear/natural term, already scaled by β).

__abstractclassvars__ class-attribute

Build an immutable unordered collection of unique elements.

__abstractmethods__ class-attribute

Build an immutable unordered collection of unique elements.

__abstractvars__ class-attribute

Build an immutable unordered collection of unique elements.

__annotations__ class-attribute

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_fields__ class-attribute

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_params__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__firstlineno__ class-attribute

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

int('0b100', base=0) 4

__match_args__ class-attribute

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__static_attributes__ class-attribute

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

__init__(diag: Array, lin: Array) -> None

Initialize self. See help(type(self)) for accurate signature.

hamon.models.QuadraticPairInteraction

Per-edge bilinear energy term coupling · x_head · x_tail.

Attributes:

• coupling: energy coefficient per head node (already scaled by β).

__abstractclassvars__ class-attribute

Build an immutable unordered collection of unique elements.

__abstractmethods__ class-attribute

Build an immutable unordered collection of unique elements.

__abstractvars__ class-attribute

Build an immutable unordered collection of unique elements.

__annotations__ class-attribute

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_fields__ class-attribute

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

__dataclass_params__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__firstlineno__ class-attribute

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

int('0b100', base=0) 4

__match_args__ class-attribute

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__static_attributes__ class-attribute

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

__init__(coupling: Array) -> None

Initialize self. See help(type(self)) for accurate signature.

hamon.models.QuadraticSelfEBMFactor

Batch of single-node energy terms ½·diag·x² − lin·x.

diag and lin carry the energy coefficients (β folded in by the EBM, mirroring the Ising factors), one per node in node_group.

__init__(node_group: Block, diag: Array, lin: Array)

hamon.models.QuadraticPairEBMFactor

Batch of pairwise bilinear energy terms coupling · x_i · x_j.

node_groups is [heads, tails] (one node pair per batch index); coupling carries the energy coefficient per pair (β folded in by the EBM). Sampling-side, the factor emits one merged interaction group covering both directions — the bilinear form is symmetric, the same head-merge the square discrete factors use.

__init__(node_groups: list[hamon.block_management.Block], coupling: Array)