Random Packing

Group: Structure | Class: RandomPackingCard

What the card does

Random Packing operates on atomic coordinates, not magnetic moments. It preserves the input cell and pbc, then redistributes atoms inside the cell using either the input composition or an explicitly specified integer composition. Global and pair-specific minimum distances reject clearly impossible short-contact starting states.

Use this card when the training set lacks structurally disordered starting configurations. For disordered magnetic moments, use Spin Disorder or Correlated Random Spin instead.

Example workflow

Scenario: a model trained only on ordered lattices gives unstable energy rankings for disordered starting states

The input is a candidate structure with a defined cell and composition. You want 20 random packings with the same cell and element counts for use as amorphous seeds, liquid starting states, or high-temperature disordered configurations for DFT sampling.

Set structures=20, composition="", min_distance=1.5, pair_min_distances="Fe-O:1.8,O-O:1.2", and strict_mode=True, then enable use_seed.

Each output preserves the original cell, periodicity, and element counts while randomizing coordinates. RandPack(...) is appended to Config_type. Validate the minimum-distance distribution and check whether subsequent DFT calculations still fail because of short contacts.

Parameters

Composition and count

Structures（structures）

int, default: 1. Number of independent random packings generated for each input structure.

Use 10–20 to probe disordered starting states. At 50 or more, placement can become slow in dense systems because each structure relies on repeated random trials, and the downstream DFT cost grows proportionally.

Composition（composition）

str, default: empty. Leave empty to preserve the input elements and atom counts. To override them, provide integer counts such as Fe:32, O:64.

Fractions such as Fe:0.33 are not accepted. Random packing requires an exact integer count for every species before placement begins.

Distance constraints

Atoms are placed one at a time. Every candidate position is checked against all atoms already placed. The following parameters define the required separation and the number of failed trials allowed before placement gives up.

Min Distance（min_distance）

float, default: 1.5 Å. Global minimum pair distance; no two atoms may be closer than this value.

A value that is too small admits bad short-contact structures, while one that is too large may make a dense cell impossible to fill. A useful starting point is 70–90% of the shortest chemically reasonable bond length. For example, with a Si–Si bond near 2.35 Å, 1.8 Å is often a sensible initial constraint.

Pair Min Distances（pair_min_distances）

str, default: empty. Element-pair overrides for the global distance, for example Fe-O:1.8, O-O:1.2.

Use pair overrides when species have substantially different sizes or contact requirements. A listed pair replaces the global constraint; unlisted pairs continue to use min_distance.

Max Attempts Per Atom（max_attempts_per_atom）

int, default: 500. Maximum random position trials for each atom before that placement is considered impossible.

Increasing this limit only spends more search time; it cannot make an infeasible packing physically possible. If most placements exhaust all 500 attempts, reduce min_distance or use a larger cell before increasing the attempt count.

Strict Mode（strict_mode）

bool, default: true. When enabled, failure to place any atom raises an error for the sample, enforcing the requested output-count contract. When disabled, failed samples are skipped and the output count may be lower than structures.

When scanning uncertain constraint combinations, disable strict mode first and inspect how many samples are accepted before tuning the parameters.

Randomness

Use Seed（use_seed）

bool, default: false. Enable it to reproduce the same packing from the same input and parameters. Use it for controlled comparisons; it may remain disabled during exploration.

Seed（seed）

int, default: 0. Used only when use_seed is enabled.

Recommended presets

Preserve the input composition

{
  "class": "RandomPackingCard",
  "params": {
    "structures": 10,
    "composition": "",
    "min_distance": 1.5,
    "pair_min_distances": "",
    "max_attempts_per_atom": 500,
    "strict_mode": true,
    "use_seed": true,
    "seed": 42
  }
}

Specify an exact composition

{
  "class": "RandomPackingCard",
  "params": {
    "structures": 20,
    "composition": "Fe:32,O:64",
    "min_distance": 1.4,
    "pair_min_distances": "Fe-O:1.8,O-O:1.2,Fe-Fe:2.0",
    "max_attempts_per_atom": 1000,
    "strict_mode": true,
    "use_seed": true,
    "seed": 7
  }
}

Recommended combinations

Crystal Prototype Builder → Super Cell → Random Packing: establish the target cell size, then generate disordered seeds in that cell.
Random Packing → Geometry Filter: generate candidates, then reject abnormal contacts, volumes, or densities.
Random Packing → Atomic Perturb: add small displacement noise to a disordered seed that already satisfies hard distance constraints.

Common questions

Why are fractional compositions not accepted? The card must construct a concrete atom list with integer counts. Rounding fractions would change their composition semantics, so determine the supercell and exact counts upstream.

Why is strict mode the default? In a card chain, downstream operations often multiply the current output count. Silently skipping failed samples would make later counts diverge from the user’s plan, so the default enforces an explicit count contract.

Output labels

RandPack(n={atom_count},d={min_distance},s={seed}). The s field appears only when use_seed=True.

Reproducibility

With use_seed enabled, the packing is determined jointly by seed, the input structure’s stable ID, and the sample index. The same input, parameters, and seed reproduce the same coordinates.