Py2Cpp4OR is a documentation-first framework for migrating mathematical optimization models and metaheuristics from Python to C++, with explicit cross-language verification.
Py2Cpp4OR 是一个文档优先的运筹优化迁移框架，用于将 Python 数学模型和元启发式算法可靠地迁移到 C++，并通过明确的跨语言验证保证一致性。
Project status / 项目状态: Phase 0 documentation is complete. The repository now also contains an experimental C++14 GVNS foundation/API draft with synthetic toy tests, CMake support, and a minimal GCC CI check. It is a prototype, not a complete GVNS library. Model translators, solver adapters, GA/Hybrid GA implementations, benchmarks, and broader CI remain roadmap items.
Moving an operations research implementation from Python to C++ is not a syntax-replacement exercise. A reliable migration must preserve:
- sets, indices, parameters, and derived data;
- variable types, bounds, and domains;
- objective direction and coefficients;
- constraint semantics and feasibility;
- algorithm operators, random-number behavior, stopping rules, and traces.
The framework therefore treats verification as part of migration, not as a final optional step.
Py2Cpp4OR is being designed around three complementary tracks:
- Model migration — document and eventually support migration from Python modeling APIs to C++ solver APIs.
- Algorithm references — provide corresponding Python and C++ implementations of generic GA/NSGA-II, exact-solver Hybrid GA, VND, and GVNS components.
- Cross-language verification — compare structure, solver behavior, algorithm traces, feasibility, and objective values.
The C++14 GVNS foundation is the only runnable algorithm prototype currently in the tree. All other implementations in tracks 1–3 remain roadmap items unless a future release explicitly marks them as available and provides runnable tests.
The project does not assume a fixed Python-modeling/solver pairing.
| Component | Role | Status in this repository |
|---|---|---|
| Pyomo | General Python algebraic modeling layer; can call multiple solvers | Documented source path |
| gurobipy | Gurobi-specific Python API | Documented source path |
| CPLEX Concert | C++ API and first planned C++ target | Roadmap |
| Gurobi C++ API | Possible future C++ target | Roadmap only |
The intended order is deliberately conservative:
- Structural verification — compare model entities, domains, bounds, objectives, constraints, and preprocessing.
- Same-solver verification — first compare
Python + Pyomo + CPLEXwithC++ + CPLEX Concert. - Cross-solver verification — only after the same-solver path passes, compare configurations such as Python/Gurobi and C++/CPLEX.
- Algorithm verification — validate RNG contracts, fixed-work traces, operators or neighborhoods, feasibility, and objective values before wall-clock benchmarking.
Different optimal variable assignments are not automatically an error: multiple optimal solutions, tolerances, and presolve can produce different representations with the same valid objective.
- Architecture
- Model migration
- Verification
- Privacy and publication boundaries
- C++14 GVNS foundation
- Anonymous case studies
- Legacy v1 notes
- Roadmap
The GVNS and test directories below are present. Other listed implementation directories remain planned and must not be inferred as available.
Py2Cpp4OR/
├── README.md
├── LICENSE
├── CMakeLists.txt
├── .github/workflows/ # minimal license-free C++ CI
├── docs/
├── model_migration/ # future
├── algorithms/
│ ├── python/ # future
│ └── cpp/
│ └── gvns/ # experimental foundation/API draft
├── solver_adapters/ # future
├── examples/ # future; public toy problems only
├── tests/
│ └── cpp/gvns/ # synthetic foundation tests
└── benchmarks/ # future
Public examples must be synthetic and free of private business context, unpublished research material, proprietary data, credentials, solver license files, and lightly renamed private source code. High-level anonymous case studies may describe migration patterns, but they are not evidence that an automated capability already exists.
See docs/privacy.md before contributing any example, trace, benchmark, or case study.
Useful contributions include improving the documentation and reviewing the experimental C++14 GVNS foundation against fully synthetic tests. Other implementation tracks require separate roadmap-scoped changes. Do not add placeholder implementations or claim verified/supported status without the required executable evidence.
Repository working rules are in agent.md and CLAUDE.md.
Licensed under the Apache License 2.0.