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 explicit rank_candidate_budgets are 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:

CSPGenerator

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 stage values arriving as raw ints or name strings (e.g. deserialized from a spec payload) are coerced to GenerationStage before 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:

BaseSpec

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.