Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
152 lines (106 loc) · 4.29 KB

CONTRIBUTING.md

File metadata and controls

152 lines (106 loc) · 4.29 KB

JRES Solver

This library can be used to solve for optimal driver and spotter schedules for endurance racing events. It uses the HiGHS optimization library.

It has been structured as a C-API library (jres_solver) and a simple CLI client (jres_solver) that uses the library.

Note

this is a C++ port of the python Solver https://github.com/popmonkey/jres_solver

Project Structure

.
├── include/
|   └── jres_solver/                # The public C-API header for the library
├── src/                            # The C++ library implementation
|   ├── jres_solver.cpp             # C-API Wrapper and Orchestrator
|   ├── jres_solver_base.cpp        # Shared logic for the solver
|   ├── jres_standard_solver.cpp    # Standard Solver (Elastic/Diagnostic enabled)
|   ├── jres_internal_types.cpp     # Internal C++ data structures
|   ├── jres_json_converter.cpp     # JSON conversion logic
|   ├── analysis/                   # Analysis logic (e.g. capacity)
|   ├── constraints/                # Constraint implementations
|   ├── formatter/                  # Formatter implementation
|   └── utils/                      # Utility functions
├── lib/
│   ├── cxxopts/                    # (Git Submodule) cxxopts header-only library
│   └── json/                       # (Git Submodule) nlohmann/json header-only library
├── cmd/
│   ├── solver/                     # A CLI solver
│   └── formatter/                  # A CLI formatter
├── test/                           # Google Test suite
└── CMakeLists.txt                  # The main build script

Bootstrap & Dependencies

This project relies on cmake for building and git for dependency management (via submodules). The only external binary dependency is the HiGHS library.

1. Clone & Init Submodules

First, clone the repo and initialize the lib submodules:

git clone git@github.com:popmonkey/jres_solver_cpp.git jres_solver_cpp
cd jres_solver_cpp
git submodule update --init --recursive

2. Install HiGHS

The HiGHS library must be installed on your system.

Note

If CMake cannot find a system-installed version of HiGHS, it will automatically download and build it as part of the project configuration process. While this simplifies setup, a pre-installed version is recommended for faster build times.

macOS (Homebrew)

This is the easiest method for macOS:

brew install highs

Linux

HiGHS is modern and may not be in the default repositories of older Linux distributions. We recommend building from source:

git clone https://github.com/ERGO-Code/HiGHS.git
cd HiGHS
cmake -B build -DFAST_BUILD=ON
cmake --build build
sudo cmake --install build

Windows

The recommended way to install HiGHS on Windows is via vcpkg:

vcpkg install highs:x64-windows-static

Building the Project

We use a standard out-of-source CMake build.

  1. Create a build directory:

    mkdir build
cd build

  2. Run CMake (Configure):

    On macOS (Homebrew):

    cmake .. -DCMAKE_PREFIX_PATH=/opt/homebrew

    On Linux:

    cmake ..

    On Windows (via vcpkg):

    cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake

  3. Run Make (Build):

    cmake --build .

This will create the main products in the build/ directory:

  • libjres_solver.so or libjres_solver.a (or .dll/.lib): The shared or static library. The type depends on the BUILD_SHARED_LIBS CMake option (defaults to ON).
  • jres_solver (or jres_solver.exe): The solver CLI executable.
  • jres_formatter (or jres_formatter.exe): The formatter CLI executable.

Running the CLI Clients

Solver

The jres_solver executable is a client that uses the jres_solver library.

# Run with a file
./jres_solver -i ../data/short_race.json -s integrated

# Run diagnostics on a failing schedule
./jres_solver -i ../data/infeasible.json --diagnose

# Get help
./jres_solver --help

Formatter

The jres_formatter executable formats solver output into various report formats.

# Get help
./jres_formatter --help