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_samplesis the accepted-output target.batch_sizelimits the active trial state, whilecandidate_budgetindependently limits total initialized candidates. The"config"default usesOverlapReliefConfig.max_candidatesand resolves"auto"to1000 * num_samples. ExplicitNonepermits 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
contextfor 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
OverlapReliefConfigvalues.
- Returns:
The accepted compact structures and one rank-local completion report. A finite budget can produce a shortfall.
- Return type:
- 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_callbackis 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.