Migration Guide¶

This guide helps you upgrade between ArqonHPO versions.

v0.2 → v0.3 (Current)¶

Breaking Changes¶

1. Config field rename: probe_budget → probe_ratio

{
  "seed": 42,
  "budget": 100,
- "probe_budget": 20,
+ "probe_ratio": 0.2,
}

1. Python import path change:

- from arqonhpo._internal import ArqonSolver
+ from arqonhpo import ArqonSolver

1. Artifact schema: history field now includes cost:

{
  "eval_id": 0,
  "params": {"x": 1.0},
  "value": 0.5,
+ "cost": 1.0
}

Migration Steps¶

1. Update config files (rename probe_budget to probe_ratio)
2. Update imports in Python code
3. Re-export artifacts from v0.2 state files:

# With v0.2
arqonhpo export --state old_state.json --output artifact.json

# Manually add "cost": 1.0 to each history entry

# With v0.3
arqonhpo import --artifact artifact.json --state new_state.json

v0.1 → v0.2¶

Breaking Changes¶

1. CLI renamed: arqon → arqonhpo

- arqon run --config config.json
+ arqonhpo run --config config.json

1. Python package renamed:

- pip install arqon
+ pip install arqonhpo

1. Config schema overhaul: Complete rewrite
2. v0.1 configs are not compatible
3. Re-create configs using v0.2 schema

Version Compatibility Matrix¶

State File Migration¶

State files are not forward compatible. To migrate state:

1. Export from old version:

# Using OLD arqonhpo version
arqonhpo export --state state.json --output artifact.json

1. Review artifact for schema changes

2. Import with new version:

   # Using NEW arqonhpo version
   arqonhpo import --artifact artifact.json --state new_state.json
   

[!WARNING] If import fails due to schema changes, you may need to manually edit the artifact JSON.

Deprecation Notices¶

v0.3 (Current)¶

v0.4 (Upcoming)¶

Getting Help¶

If you encounter migration issues:

1. Check Troubleshooting
2. Open a GitHub Issue
3. Ask in Discussions

Next Steps¶

• Installation — Install latest version
• Quickstart — Get running with v0.3
• Changelog — Full version history