Metadata-Version: 2.1
Name: simurg-ppp
Version: 0.3.0
Summary: SIMURG PPP client and workflow tools
License: MIT
Keywords: gnss,ppp,precise-point-positioning,rinex,simurg
Author: SIMURG PPP maintainers
Requires-Python: >=3.10
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Dist: matplotlib
Requires-Dist: requests
Requires-Dist: unlzw3 (>=0.2.3)
Requires-Dist: windows-curses ; sys_platform == "win32"
Description-Content-Type: text/markdown

# SIMURG PPP

SIMURG PPP is a Python client for running Precise Point Positioning workflows with SIMURG RINEX sources and a PPP processing service. It provides small command-line commands for individual PPP tasks, workflow commands for site/date processing, and an interactive terminal UI for selecting SIMURG sites and running batches.

The package is published as `simurg-ppp` and imports as `ppp_client`.

```bash
pip install simurg-ppp
```

## TUI

Run `simurg-ppp` with no subcommand to launch the interactive terminal UI:

```bash
simurg-ppp
```

![SIMURG PPP TUI demo](https://raw.githubusercontent.com/gnss-lab/simurg-ppp/main/docs/images/tui-demo.gif)

The TUI guides the SIMURG PPP workflow from the terminal. It can check service availability, verify external RINEX tools, select stored groups, choose dates, load processed SIMURG sites, select sites manually or from pasted input, and run workflow batches while showing progress and logs. Launching the TUI also creates config automatically on first run when no standard config exists; feel free to change it if needed.

Useful TUI options:

```bash
simurg-ppp --skip-startup
simurg-ppp --date 2025-11-11
simurg-ppp --storage-root workflow-data
simurg-ppp --select-only
```

For non-interactive site/date processing, use workflow commands:

```bash
simurg-ppp workflow start irkj 2025-11-11
simurg-ppp workflow proceed irkj 2025-11-11
simurg-ppp workflow status irkj 2025-11-11
simurg-ppp workflow report irkj 2025-11-11
```

## CLI

Use the atomic commands when you already have a local RINEX file or a PPP task id. 

Create configuration first if it is fresh installation and you didn't run TUI app.

```bash
simurg-ppp config init
```

`config init` creates the runtime config file and workflow storage layout in
standard system locations when permissions allow it, or in standard per-user
locations otherwise. Use `--storage-root` when you need a one-off storage
override.

### Atomic Commands

Verify optional external runtime tools:

```bash
simurg-ppp tools verify
```

Run the existing setup helpers through the installed CLI:

```bash
simurg-ppp tools install rtklib
simurg-ppp tools install hatanaka
```

### Native Windows Setup

Native Windows installs include the terminal UI dependency automatically:

```powershell
python -m pip install simurg-ppp
simurg-ppp config init
simurg-ppp config show
simurg-ppp tools verify
```

Windows machine-wide config and workflow storage are created under
`%ProgramData%\SIMURG\PPP` when writable. Otherwise, per-user config and
storage are created under `%LOCALAPPDATA%\SIMURG\PPP`. The config file is named
`ppp-client.config.json`, and workflow files live below the configured
`storage` directory.

Install external RINEX tools explicitly:

```powershell
simurg-ppp tools install rtklib
simurg-ppp tools install hatanaka
simurg-ppp tools verify
```

If you manage tools yourself, set PowerShell environment variables to the
executable paths:

```powershell
$env:PPP_CLIENT_CONVBIN = 'C:\tools\rtklib\bin\convbin.exe'
$env:PPP_CLIENT_CRX2RNX = 'C:\tools\rnxcmp\CRX2RNX.exe'
simurg-ppp tools verify
```

`.gz` compressed RINEX files use Python's standard library, and `.Z`
compressed RINEX files use the package's pure-Python `unlzw3` dependency.
WSL remains a supported alternative when you prefer the existing Linux
package-manager path for RTKLIB and RNXCMP.

Create a PPP task from a RINEX file:

```bash
simurg-ppp calculate irkj3150.25o
```

Check a PPP task status:

```bash
simurg-ppp check 0934dd49-0e75-47c9-a447-3728094929d7
```

Plot result series to a PNG. The default view is LLE: latitude with
North/South error, longitude with East/West error, elevation with Up/Down
error, and 3D error:

```bash
simurg-ppp plot 0934dd49-0e75-47c9-a447-3728094929d7 results.png
```

Use `--xyz` for the XYZ coordinate view:

```bash
simurg-ppp plot 0934dd49-0e75-47c9-a447-3728094929d7 results.png --xyz
```

## Python Usage (API)

Run a single SIMURG site/date workflow from Python:

```python
from pathlib import Path

from ppp_client.tui.workflow_runner import (
    WorkflowRunOptions,
    configure_logging,
    run_site_date_workflow,
)

configure_logging()
result = run_site_date_workflow(
    "irkj",
    "2025-11-11",
    WorkflowRunOptions(
        storage_root=Path("workflow-data"),
        force_start=False,
        poll_seconds=60.0,
        timeout_seconds=3600.0,
    ),
)

if not result.ok:
    raise RuntimeError(result.error)

print(result.report)
```

Use lower-level helpers directly when you want to compose your own flow:

```python
from ppp_client import check_task, create_task, plot_result_points
from ppp_client.results import collect_result_points

task = create_task("irkj3150.25o")
details = check_task(task["id"])
points = collect_result_points(details)
plot_result_points(points, "results.png")
```

## SIMURG Ecosystem

This package does not install a root `simurg` command. It exposes a future plugin entry point named `ppp`, so a later umbrella package can provide:

```bash
simurg ppp
simurg ppp workflow status irkj 2025-11-11
```

## Development

Install the package in editable mode, then install development tools:

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e .
pip install pytest twine build
```

Run checks:

```bash
python -m pytest -q
poetry check
```

Build release artifacts:

```bash
poetry build
python -m twine check dist/*
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/release.md](docs/release.md) for maintainer workflows.

