utils
Checkpoint save/load/cleanup helpers shared by the BlackJAX SMC and nested-sampling backends.
The four BlackJAX SMC mode samplers, BlackJAXNSSSampler, and
BlackJAXNSAWSampler each run their own JAX while-loop and periodically checkpoint it to
config.checkpoint_dir/checkpoint.pkl. The load/save/cleanup mechanics
(compute the path, try to resume, fall back to a fresh state on a corrupt or
foreign checkpoint, gate saves on the configured interval, clean up on
completion) are identical across the three; only the state shape, the extra
per-run bookkeeping (SMC's mutation history vs. NS's dead point list), and
a couple of backend-specific hooks differ. This module holds
that shared mechanics; each sampler supplies the differences via callbacks.
Functions:
| Name | Description |
|---|---|
load_or_initialize_checkpoint |
Load a compatible checkpoint or initialize a new sampler state. |
prepare_checkpointing |
Enable the JAX compile cache and return the checkpoint path and start time. |
remove_checkpoint_and_jax_cache |
Remove a completed run's checkpoint, JAX cache, and cache setting. |
save_checkpoint_if_due |
Save a checkpoint when its interval has elapsed. |
load_or_initialize_checkpoint(sampler: Sampler, checkpoint_path: Optional[Path], config: _CheckpointMixin, rng_key: Key[Array, ''], initial_particles: Any, initialize_state: Callable[..., Any], initial_extra: dict[str, Any], load_extra: Callable[[dict], dict[str, Any]], *, log_label: str, after_load: Optional[Callable[[Any], Any]] = None, is_stale: Optional[Callable[[int], bool]] = None, stale_message: str = 'checkpoint exceeds current schedule') -> tuple[Any, Key[Array, ''], int, dict[str, Any]]
¤
Load a compatible checkpoint or initialize a new sampler state.
initialize_state builds a fresh state from initial_particles.
initial_extra/load_extra supply and restore backend-specific
extras (the SMC mutation history, the NS dead point list, ...). after_load
post-processes a freshly loaded state — used for device/mesh placement
(NSS) or other backend-specific reconstruction. is_stale optionally
rejects a loaded checkpoint whose n_iter no longer fits the current
run (a fixed temperature ladder that has since changed length) and falls
back to a fresh state.
Only trusted checkpoint files may be loaded because pickle can execute arbitrary code.
prepare_checkpointing(config: _CheckpointMixin) -> tuple[Optional[Path], float]
¤
Enable the JAX compile cache and return the checkpoint path and start time.
remove_checkpoint_and_jax_cache(config: _CheckpointMixin, checkpoint_path: Optional[Path]) -> None
¤
Remove a completed run's checkpoint, JAX cache, and cache setting.
save_checkpoint_if_due(sampler: Sampler, config: _CheckpointMixin, checkpoint_path: Optional[Path], last_checkpoint_write_time: float, run_start_time: float, state: Any, rng_key: Key[Array, ''], n_completed_iterations: int, extra: dict[str, Any], *, log_label: str, before_save: Optional[Callable[[Any, Key[Array, ''], dict[str, Any]], tuple[Any, Key[Array, ''], dict[str, Any]]]] = None) -> float
¤
Save a checkpoint when its interval has elapsed.
extra is merged into the common checkpoint payload (state, rng_key,
n_iter, sampler_name, elapsed_time) — use it for backend-specific fields
such as the SMC mutation history or the NS dead point list.
before_save transforms (state, rng_key, extra) right before they
are written — e.g. NSS's jax.device_get on all three. It is called
only when a checkpoint is actually due, so a host transfer here doesn't
run every iteration. Returns the last checkpoint time.