macOS Installation

Prerequisites

  • macOS (Apple Silicon or Intel)

  • Xcode Command Line Tools (provides clang/clang++): xcode-select --install

  • Homebrew

  • Python 3.10+ via pyenv (the macOS system Python is often 3.9.x)

Note

This project is officially documented for Windows / WSL / Linux. macOS is community-supported; the steps below are verified on Apple Silicon (Homebrew prefix /opt/homebrew). On Intel Macs substitute the Homebrew prefix /usr/local wherever /opt/homebrew appears.

What is trajectory_planner?

trajectory_planner is the optimization module that computes reference attitude/control trajectories for difficult pointing maneuvers.

For more algorithm background, see https://nscheuer.github.io/SALTRO.

macOS Setup

Install the toolchain:

xcode-select --install                 # if not already installed
brew install pyenv armadillo boost

armadillo and boost are required to build trajectory_planner. cmake is not needed system-wide — it is installed as a pinned pip dependency into the virtual environment.

Install and select a supported Python:

pyenv install 3.12.13

(You do not need to change your global Python; the venv is created directly from this interpreter below.)

Instructions

Create Virtual Environment

Inside the repository root (Generalized_ADCS/):

~/.pyenv/versions/3.12.13/bin/python3 -m venv venv
source venv/bin/activate
python --version            # should print 3.12.13

Install Python dependencies using pip:

pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
pip install git+https://github.com/jcrudy/choldate.git --no-build-isolation
pip install -e . --no-deps --no-build-isolation

The --no-build-isolation flag is required for choldate because its compilation depends on Cython (already installed from requirements.txt). The final line registers the ADCS package in editable mode.

Build trajectory_planner

See the canonical installation page: [Install_Trajectory_Planner.md] (../../Install_Trajectory_Planner.md or repository root). Use the macOS section there for dependency and build commands.

Optional: Build SALTRO (saltro_py)

SALTRO installation is documented in [Install_SALTRO.md]. The canonical SALTRO page does not yet cover macOS. OldPlanner/ and SALTRO/ are both git submodules in this repository, so if you did not clone with --recurse-submodules initialise them first:

git submodule update --init --recursive OldPlanner SALTRO

The verified macOS SALTRO build (run with the virtual environment active and from the repo root) is:

cd SALTRO && mkdir -p build && cd build
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DSALTRO_WARNINGS_AS_ERRORS=OFF \
  -DPYBIND11_FINDPYTHON=ON \
  -DPython_EXECUTABLE="$VIRTUAL_ENV/bin/python" \
  -DPython_ROOT_DIR="$VIRTUAL_ENV" \
  -DPython_FIND_VIRTUALENV=ONLY
cmake --build . -j$(sysctl -n hw.logicalcpu)

Notes

  • -DSALTRO_WARNINGS_AS_ERRORS=OFF is required: SALTRO’s default -Werror -Wconversion -Wshadow does not pass under Apple clang.

  • The Python_ROOT_DIR / Python_FIND_VIRTUALENV=ONLY hints are required because the bundled pybind11 can otherwise select the Xcode framework Python and produce an incompatible artifact. Verify the artifact is SALTRO/build/saltro_py.cpython-312-darwin.so.

Known caveat

pysat (from trajectory_planner) and saltro_py both register a pybind11 class named Satellite in the process-global type registry, so importing both into the same Python process raises:

generic_type: type "Satellite" is already registered

Each works correctly on its own and via the normal ADCS.controller entry points; only co-import in one process is affected.

Debugging tplaunch

macOS uses LLDB (not GDB):

.. code-block:: bash

lldb – python examples/tutorials/06_trajectory_planner.py