Correlated Random Spin

Group: Magnetism | Class: CorrelatedRandomSpinCard

What the card does

Correlated Random Spin starts from existing moments or an element-moment map and generates a noncollinear random field with a finite spatial correlation length. It preserves each moment magnitude and changes only directions; a distance kernel and correlation_length control the correlation.

This card is deliberately not called Spin Glass: it includes no exchange Hamiltonian, frustration constraint, or dynamical cooling. Its precise training-set meaning is a spatially correlated random noncollinear spin field.

Example workflow

Scenario: PM-like random states exist, but finite-range noncollinear correlations are missing

A model handles fully random PM-like states and ordered FM/AFM states but has large magnetic-force error in short-range-correlated high-temperature states. Generate noncollinear fields with a 3 Å correlation length so nearby moments tend to align while distant directions decorrelate.

Parameters: mode=Cone around reference, correlation_kernel=exponential, correlation_length=3.0, samples=5, cone_angle=30.0, magnitude_source=Existing initial magmoms, and max_atoms_for_full=200.

Output spin has shape (N, 3) and Config_type gains CorrSpin(...). Verify preserved magnitudes, the requested cone bound, and a measurable change in neighbor-spin similarity as correlation_length changes.

Parameters

Correlated random field

Mode（mode）

str, default 'Cone around reference'. Cone around reference retains an ordered reference and adds finite-temperature noncollinear fluctuations. PM-like random field is not centered on the reference direction and targets correlated PM-like samples.

Correlation Kernel（correlation_kernel）

str, default 'exponential'. Spatial correlation kernel. exponential has a longer tail; squared_exponential is smoother and decays faster. Start with exponential for generic finite-range magnetic disorder.

Correlation Length（correlation_length）

float, default 3.0 Å. Spatial correlation length. Below the nearest-neighbor distance the field approaches independent randomness; several lattice constants create smooth domains. Scan finite values before assuming long-range correlation.

Max Atoms For Full（max_atoms_for_full）

int, default 200. Maximum atoms for full-covariance sampling, which requires an O(N³) Cholesky factorization. Keep the default for small systems; reduce a system with hundreds of magnetic atoms instead of blindly raising this limit.

Outputs and angular range

Samples（samples）

int, default 1. Random fields per correlation length. One to three trace a trend; five or more begin to sample variability at one length.

Cone Angle（cone_angle）

float, default 30.0 degrees. Maximum deviation from the reference in cone mode. About 10-30 degrees represents fluctuations near order; above 60 degrees approaches strong noncollinear disorder.

Active when mode is a cone mode.

Moment magnitudes

Magnitude Source（magnitude_source）

str, default 'Existing initial magmoms'. Source of moment magnitudes. Reuse spin:R:3 when present and accept legacy initial_magmoms only when spin is absent. If neither exists, construct magnitudes from magmom_map and default_moment. Do not replace known element moments with a generic default.

Magmom Map（magmom_map）

str, empty by default. Explicit element magnitudes such as Fe:2.2, Ni:0.6. Enter known local moments and avoid inventing priors for unknown species.

Default Moment（default_moment）

float, default 0.0. Fallback when an element is absent from magmom_map. List important magnetic species explicitly and normally keep nonmagnetic species at zero.

Lift Scalar（lift_scalar）

bool, default true. Promote scalar moments to noncollinear vectors when required downstream. Do not overwrite input that already contains directions.

Axis（axis）

list[float] | tuple[float, float, float], default (0.0, 0.0, 1.0). Reference direction in cone mode. Confirm cell orientation and the intended physical direction before changing it.

Used by modes involving a direction, layering, a surface, or vector initialization.

Apply Elements（apply_elements）

str, empty by default (all atoms). A comma-separated restriction to selected elements. In a nonmagnetic host, list magnetic species such as Fe, Co, Ni, or Mn explicitly.

Randomness

Use Seed（use_seed）

bool, default false. Enable for reproducible datasets, tests, or comparisons. Exploratory sampling may disable it, but frames will not be reproducible.

Seed（seed）

int, default 0. Fixed seed. Identical input, parameters, and seed produce identical candidates; it is used only when use_seed=True.

Active only when use_seed=True.

Recommended presets

Finite-temperature fluctuations near an ordered state

{
  "class": "CorrelatedRandomSpinCard",
  "params": {
    "mode": "Cone around reference",
    "correlation_kernel": "exponential",
    "correlation_length": 3.0,
    "samples": 5,
    "cone_angle": 25.0,
    "magnitude_source": "Existing initial magmoms",
    "magmom_map": "",
    "default_moment": 0.0,
    "lift_scalar": true,
    "axis": [0.0, 0.0, 1.0],
    "apply_elements": "",
    "max_atoms_for_full": 200,
    "use_seed": true,
    "seed": 42
  }
}

Correlated PM-like random directions

{
  "class": "CorrelatedRandomSpinCard",
  "params": {
    "mode": "Full random directions",
    "correlation_kernel": "exponential",
    "correlation_length": 5.0,
    "samples": 3,
    "cone_angle": 30.0,
    "magnitude_source": "Map/default magnitude",
    "magmom_map": "Fe:2.2,Co:1.7",
    "default_moment": 0.0,
    "lift_scalar": true,
    "axis": [0.0, 0.0, 1.0],
    "apply_elements": "Fe,Co",
    "max_atoms_for_full": 200,
    "use_seed": true,
    "seed": 7
  }
}

Recommended combinations

Set Magnetic Moments -> Correlated Random Spin: establish magnitudes before generating a correlated noncollinear state.
Magnetic Order -> Correlated Random Spin: generate finite-temperature cone disorder from an FM or AFM reference.
Spin Disorder -> Correlated Random Spin: set a discrete flip fraction, then add spatially correlated directional fluctuations.

Common questions

Why does the card fail above max_atoms_for_full? Exact covariance sampling needs a full matrix and Cholesky factorization. Silently changing to an approximation would change semantics with system size, so v1 fails explicitly.

Which kernel should I use? Start with exponential; choose squared_exponential only when a smoother, shorter-tailed field is intended.

What if no moments are available? The card fails when neither usable spin nor legacy initial_magmoms nor nonzero mapped/default magnitudes exist. It does not emit a fake zero-moment result.

Output labels

CorrSpin(xi={correlation_length},ker={kernel},mode={cone|full},n={eligible_atoms},s={seed},a={cone_angle}); s appears only with use_seed=True, and a only in cone mode.

All exported outputs use spin:R:3; an ASE vector-valued initial_magmoms alias is kept in sync internally.

Reproducibility

With use_seed enabled, the field is determined by the seed, stable input ID, and sample index. Identical inputs and parameters reproduce directions.