nvalchemi.csp.CSPGenerator#
- class nvalchemi.csp.CSPGenerator(packer, *, process_group=None, gather_to_rank=None, expand=True, outputs=None, on_result=None, hooks=<factory>, step_count=0, generator_func, condition_func=None, device=None, dedicated_stream=True, required_inputs=None, num_samples=1, seed=None, enable_inference_mode=False, compile_generate=False, compile_kwargs=<factory>)[source]#
A Toolkit generation driver for running crystal packers in local or distributed searches.
The packer determines the search algorithm and execution device. By default, compact ASU structures are expanded into full-cell atomic Batches; packers that already return Batches require no expansion. Search limits can leave fewer accepted structures than requested.
Distributed generation shares the search across a process group. Each rank supplies the same prepared molecular input. Results can remain on their generating ranks or be gathered on one rank. With custom
rank_targets, a finite candidate budget is divided proportionally unless explicitrank_candidate_budgetsare supplied.- Parameters:
packer (CrystalPacker) – CrystalPacker implementing device and pack(inputs, num_samples, rng, context).
process_group (ProcessGroup | None) – Optional initialized process group. The caller owns group lifetime and rank launch.
gather_to_rank (int | None) – Optional group-local destination for rank-major gathered output. None leaves each rank’s result local.
expand (bool) – Expand rigid ASU structures to a Toolkit Batch on the owning rank. Existing Batch payloads pass through.
outputs (frozenset[str] | None) – Optional complete declaration of fields guaranteed in expanded Batch results. Defaults to
CSP_OUTPUT_FIELDS. Include additional fields when the packer guarantees them; declarations are checked on each nonempty result. Raw-result mode (expand=False) accepts only an empty declaration.on_result (Callable[[PackingResult], None] | None) – Optional callable receiving the owning PackingResult after any communication and before optional P1 expansion or generation hooks.
**generator_options – Supported AtomisticGenerator lifecycle options: conditioning, hooks, seed, default num_samples, dedicated stream, inference mode, and compile_generate. CSP packing is not torch.compile-compatible.
hooks (list[Hook])
step_count (Annotated[int, Ge(ge=0)])
generator_func (GeneratingFunction)
condition_func (ConditionFunction | None)
device (Annotated[device, BeforeValidator(func=~nvalchemi._serialization._wrap_custom_type.<locals>._before, json_schema_input_type=PydanticUndefined), PlainSerializer(func=str, return_type=PydanticUndefined, when_used=always)] | None)
dedicated_stream (bool)
required_inputs (frozenset[str] | None)
num_samples (Annotated[int, Ge(ge=1)])
seed (int | None)
enable_inference_mode (bool)
compile_generate (bool)
compile_kwargs (dict[str, Any])
- compile(**kwargs)[source]#
Reject driver-level compilation for the dynamic packing lifecycle.
- Parameters:
kwargs (Any)
- Return type:
- model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid'}#
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- model_post_init(_AtomisticGenerator__context)#
Bind the execution device, register hooks, and initialize run state.
Hook
stagevalues arriving as raw ints or name strings (e.g. deserialized from a spec payload) are coerced toGenerationStagebefore registration.- Parameters:
_AtomisticGenerator__context (Any)
- Return type:
None
- to_spec()[source]#
Capture the construction recipe for this local CSP generator.
The recipe retains constructor settings and rebuilds the packer, callbacks, and hooks. Runtime session state and the active distributed process group are not serializable.
- Returns:
A JSON-serializable construction recipe.
- Return type:
- Raises:
TypeError – If a live process group is attached, or a packer or callback does not provide an importable path or its own
to_spec()method.