Checkpointing

Checkpointing

Long-running variational quantum algorithms can be interrupted by timeouts, crashes, or resource limits. Divi’s checkpointing system lets you save optimization state at regular intervals and resume from the last checkpoint, avoiding the need to restart from scratch.

Enabling Checkpointing

Pass a CheckpointConfig to any variational algorithm:

from pathlib import Path
from divi.qprog import VQE, HartreeFockAnsatz
from divi.qprog.optimizers import ScipyOptimizer, ScipyMethod
from divi.qprog.checkpointing import CheckpointConfig
from divi import ParallelSimulator

vqe = VQE(
    molecule=molecule,
    ansatz=HartreeFockAnsatz(),
    optimizer=ScipyOptimizer(ScipyMethod.COBYLA),
    max_iterations=100,
    backend=ParallelSimulator(),
    checkpoint_config=CheckpointConfig(
        checkpoint_dir=Path("./checkpoints/my_vqe_run"),
        save_every_n=5,  # Save every 5 iterations
    ),
)

vqe.run()

Checkpoint Structure

Checkpoints are saved as numbered subdirectories:

checkpoints/my_vqe_run/
├── checkpoint_001/
│   ├── program_state.json
│   └── optimizer_state.json
├── checkpoint_005/
│   ├── program_state.json
│   └── optimizer_state.json
└── checkpoint_010/
    ├── program_state.json
    └── optimizer_state.json

Each checkpoint contains:

• program_state.json: Algorithm state (parameters, losses, iteration count, subclass-specific data)
• optimizer_state.json: Optimizer internal state (for seamless continuation)

Resuming from a Checkpoint

To resume, load the checkpoint before calling run():

from divi.qprog.checkpointing import resolve_checkpoint_path

# Resume from the latest checkpoint
checkpoint_path = resolve_checkpoint_path("./checkpoints/my_vqe_run")
vqe.load_checkpoint(checkpoint_path)
vqe.run()  # Continues from where it left off

You can also resume from a specific checkpoint:

checkpoint_path = resolve_checkpoint_path(
    "./checkpoints/my_vqe_run",
    subdirectory="checkpoint_005"
)
vqe.load_checkpoint(checkpoint_path)

Supported Algorithms

Checkpointing is supported by all algorithms that extend VariationalQuantumAlgorithm:

• VQE
• QAOA
• PCE
• CustomVQA

When to Use Checkpointing

• Cloud execution: Long-running jobs may hit timeout limits
• Expensive simulations: MPS simulations on large circuits
• Hyperparameter exploration: Resume with different optimizer settings
• Reliability: Protect against crashes and interruptions