nvalchemi.csp.packer.OverlapReliefPacker#

class nvalchemi.csp.packer.OverlapReliefPacker(config, *, device)[source]#

Generate molecular crystal starting structures from supplied conformers.

The Packer selects conformers, places molecules in periodic cells, and translates or rotates whole molecules to reduce intermolecular clashes. It can also change the cell. Molecular geometry stays fixed, and accepted structures meet the configured overlap tolerance. Energy minimization with a physical model is a separate step. Required arrays are transferred to the selected device when needed; accepted ASU representations retain the original input object.

Parameters:
  • config (OverlapReliefConfig) – Immutable base configuration containing z, z_prime, sampling controls, candidate capacity, and the optional finite candidate budget. The requested accepted count belongs to each call.

  • device (torch.device or str) – Explicit execution device, either "cpu" or "cuda:N".

pack(inputs, *, num_samples=1, rng=None, context=None, run_id=None, candidate_budget='config', progress_callback=None, **config_overrides)[source]#

Generate and return compact ASU structures on this process only.

num_samples is the accepted-output target. batch_size limits the active trial state, while candidate_budget independently limits total initialized candidates. The "config" default uses OverlapReliefConfig.max_candidates and resolves "auto" to 1000 * num_samples. Explicit None permits unlimited trials; zero requests a typed shortfall without sampling or trial setup.

Parameters:
  • inputs (MolecularPackingInput) – One validated formula-unit tensor input.

  • num_samples (int, default=1) – Nonnegative requested number of accepted outputs.

  • rng (torch.Generator, optional) – Generator used for one int64 seed draw when candidates are sampled. Zero target or zero candidate budget does not consume it.

  • context (PackingContext, optional) – Call identity and rank used to assign rank-strided structure IDs.

  • run_id (int, optional) – Alternative to context for a local rank-zero identity.

  • candidate_budget (int or None or {"config"}, default="config") – Local cap on initialized candidates; unlike the positive config cap, an explicit zero is allowed.

  • progress_callback (callable, optional) – Called at performed convergence checks with cumulative counters and current overlap diagnostics.

  • **config_overrides – Per-call OverlapReliefConfig values.

Returns:

The accepted compact structures and one rank-local completion report. A finite budget can produce a shortfall.

Return type:

PackingResult[RigidMoleculeASUBatch]

Raises:

RuntimeError – If cell rejection sampling cannot fill candidate rows in 128 rounds.

resolve_candidate_budget(*, num_samples, **pack_options)[source]#

Resolve this call’s candidate cap without drawing randomness.

The generic generation driver uses this optional capability to report whether a requested output target has a finite candidate budget. progress_callback is a concrete pack option and is validated before configuration fields are evaluated.

Parameters:
  • num_samples (int) – Nonnegative number of accepted structures.

  • **pack_options – Configuration overrides and the optional progress callback.

Returns:

Resolved nonnegative cap, or None for unlimited candidates.

Return type:

int or None

Raises:
  • TypeError – If the count or progress callback has an invalid type.

  • ValueError – If the count or effective configuration is invalid.

to_spec()[source]#

Capture this packer’s configuration and resolved execution device.

Returns:

A JSON-serializable constructor recipe for a fresh packer.

Return type:

BaseSpec