siderust-cpp

Modern, header-only C++17 wrapper for siderust — a high-precision astronomical computation library written in Rust.

siderust-cpp provides idiomatic C++ types (RAII, exceptions, value semantics) on top of the C FFI layer generated by siderust-ffi and tempoch-ffi.

Features

Module	What you get
Time (time.hpp)	JulianDate, MJD, UTC, Period — value types with arithmetic and UTC round-trips
Coordinates (coordinates.hpp)	Modular typed API (coordinates/{geodetic,spherical,cartesian,types}.hpp) plus selective alias headers under coordinates/types/{spherical,cartesian}/...
Bodies (bodies.hpp)	Star (RAII, catalog + custom), Planet (8 planets), ProperMotion, Orbit
Observatories (observatories.hpp)	Named sites: Roque de los Muchachos, Paranal, Mauna Kea, La Silla
Altitude (altitude.hpp)	Sun / Moon / Star / ICRS altitude: instant, above/below threshold, crossings, culminations
Ephemeris (ephemeris.hpp)	VSOP87 Sun/Earth positions, ELP2000 Moon position

Quick Start

#include <siderust/siderust.hpp>
#include <cstdio>

int main() {
    using namespace siderust;
    using namespace qtty::literals;

    auto obs  = ROQUE_DE_LOS_MUCHACHOS;
    auto jd   = JulianDate::from_utc({2026, 7, 15, 22, 0, 0});
    auto mjd  = MJD::from_jd(jd);

    // Sun altitude
    qtty::Radian alt = sun::altitude_at(obs, mjd);
    std::printf("Sun altitude: %.4f rad\n", alt.value());

    // Star from catalog
    const auto& vega = VEGA;
    qtty::Radian star_alt = star_altitude::altitude_at(vega, obs, mjd);
    std::printf("Vega altitude: %.4f rad\n", star_alt.value());

    // Night periods (astronomical twilight)
    auto nights = sun::below_threshold(obs, mjd, mjd + 1.0, -18.0_deg);
    for (auto& p : nights)
        std::printf("Night: MJD %.4f – %.4f\n", p.start_mjd(), p.end_mjd());

    return 0;
}

Building

# Clone with submodules
git clone --recurse-submodules <url>
cd siderust-cpp

# Build
mkdir build && cd build
cmake ..
cmake --build .

# Run example
./siderust_demo
./coordinates_examples
./coordinate_systems_example
./solar_system_bodies_example
./altitude_events_example

# Run tests
ctest --output-on-failure

Docker

The repository includes a root Dockerfile that installs all build dependencies (CMake, Rust, Doxygen), then runs configure/build/tests/docs during image build.

# Clone with submodules
git clone --recurse-submodules <url>
cd siderust-cpp

# Build image (validates build + tests + docs)
docker build -t siderust-cpp:dev .

# Open an interactive shell in the container
docker run --rm -it -v "$PWD":/workspace -w /workspace siderust-cpp:dev

Note: docker build writes generated docs inside the image layer, not your host filesystem.

To generate docs on the host, run the docs target in a bind-mounted container:

docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/workspace \
  -w /workspace \
  siderust-cpp:dev \
  bash -lc 'cmake -S . -B build -G Ninja && cmake --build build --target docs'

Generated HTML entry point on host:

• build/docs/doxygen/html/index.html

Generated HTML entry point inside container:

• /workspace/build/docs/doxygen/html/index.html

API Documentation (Doxygen)

If Doxygen is installed, CMake exposes a docs target:

cmake -S . -B build
cmake --build build --target docs

Generated HTML entry point:

• build/docs/doxygen/html/index.html

Prerequisites

• C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)
• CMake 3.15+
• Rust toolchain (cargo) — Rust FFI libraries are built automatically
• Internet connection for Google Test (fetched automatically)

Project Layout

siderust-cpp/
├── CMakeLists.txt
├── docs/
│   ├── Doxyfile.in
│   └── mainpage.md
├── cmake/
│   └── siderust_cppConfig.cmake.in
├── include/siderust/
│   ├── siderust.hpp          ← umbrella header
│   ├── ffi_core.hpp          ← error handling, enums
│   ├── time.hpp              ← JulianDate, MJD, Period, UTC
│   ├── coordinates.hpp       ← coordinate umbrella header
│   ├── coordinates/
│   │   ├── geodetic.hpp
│   │   ├── spherical.hpp
│   │   ├── cartesian.hpp
│   │   ├── types.hpp
│   │   └── conversions.hpp
│   ├── bodies.hpp            ← Star, Planet, ProperMotion
│   ├── observatories.hpp     ← named observatory locations
│   ├── altitude.hpp          ← sun/moon/star altitude API
│   └── ephemeris.hpp         ← VSOP87/ELP2000 positions
├── examples/demo.cpp
├── tests/
│   ├── main.cpp
│   ├── test_time.cpp
│   ├── test_observatories.cpp
│   ├── test_coordinates.cpp
│   ├── test_bodies.cpp
│   ├── test_altitude.cpp
│   └── test_ephemeris.cpp
├── siderust-ffi/             ← git submodule (contains `siderust` as nested submodule)
└── qtty-cpp/                 ← git submodule

Architecture

┌──────────────┐
│  C++ user    │   #include <siderust/siderust.hpp>
│  code        │
└──────┬───────┘
       │  header-only (inline)
┌──────▼───────┐
│ siderust-cpp │   C++17 types, RAII, exceptions
│ (headers)    │
└──────┬───────┘
       │  extern "C" calls
┌──────▼───────┐  ┌──────────────┐
│ siderust-ffi │──│ tempoch-ffi  │   C ABI (cbindgen-generated)
│ (.so/.dylib) │  │ (.so/.dylib) │
└──────┬───────┘  └──────┬───────┘
       │                 │
┌──────▼─────────────────▼──┐
│       siderust (Rust)     │
│  coordinates · altitude   │
│  bodies · ephemeris       │
│  tempoch · affn · qtty    │
└───────────────────────────┘

License

Same license as siderust. See LICENSE.