Metadata-Version: 2.1
Name: simurg-ppp
Version: 0.1.2
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 :: OS Independent
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
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
```

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 XYZ result series to a PNG:

```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_xyz_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_xyz_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.

