Getting Started

This page walks through a complete LuPNT setup from a fresh machine: installing the toolchain, building the C++ library and Python bindings, verifying the install, registering the Jupyter kernel, and configuring the NASA Earthdata credentials needed by the data-driven GNSS examples and tests. For a first overview of what LuPNT is, see Introducing LuPNT; for the developer workflow (build variants, debugging, VS Code) see Development with VSCode.

All dependencies — the C++ compiler toolchain, CMake/Ninja, Python, and every C++/Python package — are provisioned by Pixi from conda-forge, so you do not install any compiler or library by hand.

1. Prerequisites

  • Pixi — the only tool you install manually:

    curl -fsSL https://pixi.sh/install.sh | bash

    Restart the shell (or source your profile) so pixi is on PATH.

  • Git — to clone the repository.

  • Windows — build and run inside WSL2 (Ubuntu), not native Windows; create the ~/.netrc file (Step 6) inside WSL as well.

  • Disk — the bundled data set (SPICE kernels, gravity fields, ephemerides, TLEs) is ~1 GB and is downloaded automatically on the first build.

2. Clone the repository

git clone https://github.com/Stanford-NavLab/LuPNT.git
cd LuPNT

Note

The optical-navigation / stereo research code under python/thirdparty lives in git submodules. The core library and all numbered examples build without them; fetch them only if you need those projects, with git submodule update --init --recursive.

3. Install the environment

From the repository root, provision the isolated conda-forge environment (this downloads the toolchain and all dependencies into .pixi/ — it does not touch your system Python or compilers):

pixi install

Every subsequent command is run through Pixi, either as pixi run <task> or from inside an activated shell:

pixi shell        # activate the environment (exit with `exit`)
# ...or prefix individual commands:
pixi run <task>

4. Build LuPNT

pixi run build       # build the C++ library (target: lupnt)
pixi run build-py    # build and deploy the Python bindings (_pylupnt)

Note

The first build downloads the bundled LuPNT_data set (SPICE kernels, gravity fields, ephemerides, EOP/TAI-UTC tables, TLEs) via cmake/FetchLuPNTData.cmake; later builds skip it. No credentials are needed for this bundled data — only the live GNSS products in Step 6 require an Earthdata login.

Optionally build the standalone C++ tutorial programs:

pixi run build-examples          # builds all_examples into build-examples-pixi/
./build-examples-pixi/ex1_propagate_orbit

5. Verify the install

Inside pixi shell the pylupnt package is already importable (PYTHONPATH and the data paths are set by the environment):

python -c "import pylupnt as pnt; print(pnt.R_MOON)"

Run the test suites and a first example:

pixi run test-py                 # Python tests (no credentials needed)
pixi run test-cpp                # C++ tests (some GNSS tests need Earthdata — Step 6)
python python/examples/ex1_propagate_orbit.py

6. NASA Earthdata credentials (for the GNSS examples)

The Earth-GNSS examples — ex3, ex5, ex6, and their Python notebooks — plus a few pixi run test-cpp cases download precise SP3/BRDC/ANTEX products from NASA CDDIS, which requires a free NASA Earthdata Login. All non-GNSS examples run from the bundled data with no credentials.

Step 1 — create an account at urs.earthdata.nasa.gov (“Register for a profile”).

Step 2 — create a ~/.netrc file in your home directory (on Windows, inside WSL). Note it is ~/.netrc, not a file in the repository:

touch ~/.netrc
chmod 0600 ~/.netrc
echo "machine urs.earthdata.nasa.gov login <your_username> password <your_password>" >> ~/.netrc

Warning

The chmod 0600 step is required — curl/wget refuse to use a world-readable .netrc. Keep this file private and never commit it; it lives outside the repository at ~/.netrc, so it cannot be checked into git.

Step 3 (alternative) — for short local tests both loaders also read the credentials from environment variables instead of ~/.netrc:

export EARTHDATA_USERNAME="<your_username>"
export EARTHDATA_PASSWORD="<your_password>"

Step 4 — on the first scripted CDDIS access, sign in through a browser once and approve any Earthdata application-access prompt for CDDIS.

The full download workflow (cache location, running the Python/C++ SP3 examples, and the ex6 precompute stages) is on the SP3 Downloads page.

7. Jupyter / notebook setup

The Python example notebooks under python/examples run in a dedicated kernel that bakes in PYTHONPATH, LUPNT_DATA_PATH, and the other runtime paths, so import pylupnt and the data-backed examples work when the kernel is launched directly by Jupyter or VS Code (outside Pixi activation). Register it once per machine:

pixi run install-kernel     # registers the "LuPNT (pixi)" kernel

Then select the LuPNT (pixi) kernel in Jupyter or VS Code.

8. Next steps

  • Python and C++ — the worked examples (start with ex1_propagate_orbit).

  • How to Create a New Simulation — the agent-based architecture and the workflow for building your own scenario.

  • Math Specifications — the mathematical specifications for the dynamics, measurement, and estimation models.