|
| 1 | +# Gemini Project: JRES Solver C++ |
| 2 | + |
| 3 | +This document provides instructions for understanding, building, and contributing to the JRES Solver C++ project. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +JRES Solver is a C++ library designed to optimize endurance racing schedules. It uses the HiGHS Mixed Integer Programming (MIP) solver to assign drivers and optional spotters to race stints while satisfying various constraints. |
| 8 | + |
| 9 | +The project is structured as a C-API library (`libjres_solver.a`) with two command-line interface (CLI) clients: |
| 10 | +* `jres_solver`: A tool that uses the library to solve race schedules. |
| 11 | +* `jres_formatter`: A tool to format the output of the solver. |
| 12 | + |
| 13 | +The library provides helper functions to convert between its C-API data structures and JSON, making it easier to integrate with other systems. |
| 14 | + |
| 15 | +### Public headers |
| 16 | + |
| 17 | +The library exposes its API via headers in `include/jres_solver/`. Designed for seamless Foreign Function Interface (FFI) integration with languages like Python, Ruby, and Go, these headers are strictly: |
| 18 | +* **C-Compatible:** All exported symbols utilize extern "C" linkage. |
| 19 | +* **Self-Contained:** The interface uses standard C types and opaque handles only, ensuring no dependency on the C++ Standard Library (STL) at the boundary. |
| 20 | +* **Standalone:** Each header is fully self-sufficient and requires no prior includes. |
| 21 | + |
| 22 | +## Building and Running |
| 23 | + |
| 24 | +This project uses CMake for building. |
| 25 | + |
| 26 | +### Dependencies |
| 27 | + |
| 28 | +* **CMake (version 3.15+)** |
| 29 | +* **Git** (for managing submodules) |
| 30 | +* **HiGHS Optimization Solver**: This must be installed on your system. |
| 31 | + * **macOS (Homebrew):** `brew install highs` |
| 32 | + * **Linux:** Build from source (see `CONTRIBUTING.md`). |
| 33 | + * **Windows (vcpkg):** `vcpkg install highs:x64-windows-static` |
| 34 | + |
| 35 | +### Build Steps |
| 36 | + |
| 37 | +1. **Clone the repository and initialize submodules:** |
| 38 | + ```bash |
| 39 | + git clone <repository_url> jres_solver_cpp |
| 40 | + cd jres_solver_cpp |
| 41 | + git submodule update --init --recursive |
| 42 | + ``` |
| 43 | + |
| 44 | +2. **Configure the project with CMake:** |
| 45 | + ```bash |
| 46 | + mkdir build |
| 47 | + cd build |
| 48 | + # Add platform-specific flags if needed, e.g., for macOS with Homebrew: |
| 49 | + # cmake .. -DCMAKE_PREFIX_PATH=/opt/homebrew |
| 50 | + cmake .. |
| 51 | + ``` |
| 52 | + |
| 53 | +3. **Build the project:** |
| 54 | + ```bash |
| 55 | + cmake --build . |
| 56 | + ``` |
| 57 | + This will generate the library and executables in the `build/` directory. |
| 58 | + |
| 59 | +### Running Tests |
| 60 | + |
| 61 | +The project uses GoogleTest for its test suite. To run the tests, execute the following command from the `build` directory: |
| 62 | + |
| 63 | +```bash |
| 64 | +ctest |
| 65 | +``` |
| 66 | + |
| 67 | +### Running the CLI Tools |
| 68 | + |
| 69 | +The compiled executables are located in the `build/` directory. |
| 70 | + |
| 71 | +**Solver (`jres_solver`):** |
| 72 | + |
| 73 | +```bash |
| 74 | +# Run with an input file |
| 75 | +./jres_solver -i ../data/short_race.json -s integrated |
| 76 | +
|
| 77 | +# Pipe data from stdin and output to a file |
| 78 | +cat ../data/24h_race.json | ./jres_solver -s sequential -o /tmp/24_race_solution.json |
| 79 | +
|
| 80 | +# Run diagnostics on an infeasible schedule |
| 81 | +./jres_solver -i ../data/short_race_no_solution.json --diagnose |
| 82 | +``` |
| 83 | + |
| 84 | +**Formatter (`jres_formatter`):** |
| 85 | + |
| 86 | +The formatter takes the JSON output from the solver and can generate different report formats. |
| 87 | + |
| 88 | +```bash |
| 89 | +# Load a solution and generate a txt summary |
| 90 | +./jres_formatter -i /tmp/24_race_solution.json -o /tmp/summary.txt |
| 91 | +``` |
| 92 | + |
| 93 | +## Development Conventions |
| 94 | + |
| 95 | +* **Build System:** The project uses CMake for building and configuration. |
| 96 | +* **Dependencies:** C++ library dependencies are managed as Git submodules (`cxxopts`, `nlohmann/json`). The HiGHS solver is an external dependency. |
| 97 | +* **Testing:** The test suite is built with GoogleTest and run via CTest. New tests should be added to the `test/` directory. |
| 98 | +* **API Design:** The core logic is exposed as a C-API for wider compatibility. Helper functions are provided for JSON serialization and deserialization. |
| 99 | +* **Code Style:** The codebase is written in C++. Please follow the existing coding style when contributing. |
| 100 | + |
| 101 | +# MODEL INSTRUCTIONS |
| 102 | +- **Verbosity:** Low. Do not explain the code unless asked. Just output the diff or the file. |
| 103 | +- **Reasoning:** Perform deep reasoning internally, but output only the final solution. |
| 104 | +- **Execution:** Don't stage commits or otherwise try to manage the repo. |
0 commit comments