Skip to content

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.