orbital-pv 0.3.0__tar.gz

orbital_pv-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orbital_pv-0.3.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: orbital-pv
+Version: 0.3.0
+Summary: Open-source spacecraft photovoltaic performance analytics
+Author: OrbitalPV contributors
+License-Expression: MIT
+Project-URL: Documentation, https://julianascencio.github.io/orbital-pv/
+Project-URL: Source, https://github.com/julianascencio/orbital-pv
+Project-URL: Issues, https://github.com/julianascencio/orbital-pv/issues
+Keywords: photovoltaics,space,satellite,orbit,solar,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: numpy>=2.3
+Requires-Dist: pandas>=2.2
+Requires-Dist: pvlib<0.16,>=0.15.2
+Provides-Extra: orbit
+Requires-Dist: astropy<9,>=8.0; extra == "orbit"
+Requires-Dist: skyfield<2,>=1.55; extra == "orbit"
+Requires-Dist: sgp4<3,>=2.27; extra == "orbit"
+Requires-Dist: spiceypy<9,>=8.2; extra == "orbit"
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == "excel"
+Provides-Extra: radiation
+Requires-Dist: spacepy>=0.7; extra == "radiation"
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.10; extra == "examples"
+Provides-Extra: app
+Requires-Dist: celery[redis]<6,>=5.6; extra == "app"
+Requires-Dist: duckdb<2,>=1.5; extra == "app"
+Requires-Dist: fastapi<1,>=0.141; extra == "app"
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "app"
+Requires-Dist: pydantic-settings<3,>=2.7; extra == "app"
+Requires-Dist: sqlalchemy<3,>=2.0; extra == "app"
+Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "app"
+Provides-Extra: full
+Requires-Dist: astropy<9,>=8.0; extra == "full"
+Requires-Dist: celery[redis]<6,>=5.6; extra == "full"
+Requires-Dist: duckdb<2,>=1.5; extra == "full"
+Requires-Dist: fastapi<1,>=0.141; extra == "full"
+Requires-Dist: matplotlib>=3.10; extra == "full"
+Requires-Dist: openpyxl>=3.1; extra == "full"
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "full"
+Requires-Dist: pydantic-settings<3,>=2.7; extra == "full"
+Requires-Dist: sgp4<3,>=2.27; extra == "full"
+Requires-Dist: skyfield<2,>=1.55; extra == "full"
+Requires-Dist: spacepy>=0.7; extra == "full"
+Requires-Dist: spiceypy<9,>=8.2; extra == "full"
+Requires-Dist: sqlalchemy<3,>=2.0; extra == "full"
+Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "full"
+Dynamic: license-file
+
+# OrbitalPV
+
+Open-source full-stack lab for **spacecraft photovoltaic performance analytics**: PV physics, orbit/Sun geometry, real spacecraft data connectors, degradation/anomaly analytics, reproducible research labs, and a web application platform.
+
+The structure follows a modular separation-of-concerns approach: domain models, physics engines, connectors and analytics are independent workspace packages with consistent quality tooling.
+
+## Install from PyPI
+
+```bash
+python -m pip install orbital-pv
+```
+
+Use the public API as:
+
+```python
+import orbitalpv as opv
+
+positions_m = opv.circular_orbit_positions_m(
+    altitude_m=550_000.0,
+    inclination_deg=51.6,
+)
+
+g_am0 = opv.am0_irradiance(opv.ASTRONOMICAL_UNIT_M)
+```
+
+Optional extras:
+
+```bash
+python -m pip install "orbital-pv[examples]"
+python -m pip install "orbital-pv[orbit]"
+python -m pip install "orbital-pv[full]"
+```
+
+## Foundation stack
+
+- **pvlib** — tested PV equations and I-V/single-diode reference models behind a space-specific adapter.
+- **Skyfield + python-sgp4** — Earth-orbit catalog propagation from CCSDS OMM/TLE.
+- **Astropy** — time, units, frames and baseline solar-system coordinates.
+- **SpiceyPy / NASA SPICE** — mission-grade ephemeris, attitude, clocks and frame transforms.
+- **SpacePy / later radiation engines** — radiation/environment workstream.
+- **HTTP connectors** — CelesTrak, Space-Track, NASA SSCWeb, NAIF, CDAWeb/HAPI, NOAA SWPC, SatNOGS DB and BIRDS EPS.
+
+`poliastro` is intentionally not a core dependency because its upstream repository is archived.
+
+## Repository map
+
+```text
+orbital-pv/
+├── src/orbitalpv/                 # public PyPI API
+├── apps/
+│   ├── space-pv-cli/
+│   ├── space-pv-api/
+│   └── space-pv-web/
+├── packages/
+│   ├── space-pv-core/
+│   ├── space-pv-orbit/
+│   ├── space-pv-pvmodel/
+│   ├── space-pv-space-env/
+│   ├── space-pv-connectors/
+│   ├── space-pv-analytics/
+│   ├── space-pv-storage/
+│   └── space-pv-orchestration/
+├── examples/
+├── labs/
+├── data/{raw,bronze,silver,gold}/
+├── docs/
+└── tests/
+```
+
+The `space_pv_*` packages remain available as lower-level implementation modules for contributors and advanced use, while `orbitalpv` is the stable user-facing import.
+
+## Documentation
+
+**https://julianascencio.github.io/orbital-pv/**
+
+The documentation uses Sphinx, PyData Sphinx Theme, and Sphinx-Gallery. Gallery examples execute during the documentation build and use the same `orbitalpv` API installed from PyPI.
+
+Build locally:
+
+```bash
+make docs
+```
+
+## Development
+
+```bash
+uv sync --all-packages --group dev --group lab --group orbit --group pv --group space --group app
+uv run pytest
+uv run ruff check .
+uv run ty check
+```
+
+## Science pipeline
+
+```text
+real orbit/telemetry/environment data
+              |
+              v
+      canonical time + frames
+              |
+    +---------+----------+
+    |                    |
+orbit + Sun          PV telemetry
+    |                    |
+    v                    |
+eclipse + AOI + AM0      |
+    |                    |
+    +----------+---------+
+               v
+      expected PV performance
+               |
+               v
+       residual / degradation
+               |
+               v
+      anomaly + EOL analytics
+```
+
+See `docs/foundation_stack.md`, `docs/connectors/catalog.md`, `docs/architecture.md` and `docs/state_of_art.md`.
+
+## Application platform
+
+The web/application layer is intentionally separated from the scientific packages:
+
+- **React + TypeScript + Vite** — frontend application.
+- **FastAPI** — API and job submission boundary.
+- **PostgreSQL** — durable multi-user/transactional application state and job metadata.
+- **DuckDB** — local analytics, parquet-backed research datasets and fast time-series exploration.
+- **Celery + Redis** — long-running ingestion, orbit, PV and analytics jobs.
+- **Flower** — local Celery worker/task observability.
+
+Start the development stack with:
+
+```bash
+docker compose up --build
+```
+
+Then open React on `http://localhost:5173`, FastAPI docs on `http://localhost:8000/docs`, and Flower on `http://localhost:5555`.
+
+## Space GIS and dynamic visualization
+
+The platform separates scientific orbital reference-frame state from Earth-fixed GIS render products. PostGIS serves hot satellite positions, ground tracks, stations and footprints; DuckDB/Parquet retain analytical history and chart rollups; CesiumJS renders time-dynamic 3D orbital scenes. See `docs/space_gis_and_visualization.md`.
+
+## Literature library
+
+A curated, source-tagged literature library is maintained in [`docs/literature/`](docs/literature/README.md). It covers the 2026 state of the art in space-PV cells and arrays, mission-aware performance modelling, radiation/degradation, digital twins, telemetry/AI, and open flight datasets/APIs.
+
+## Roadmap evidence
+
+- `docs/literature/09_ieso_2026_workshop_roadmap.md` — 2026 IESO workshop targets translated into repository features and R&D priorities.
+- `docs/product_feature_roadmap.md` — prioritized product epics derived from the literature and 2026 IESO workshop.

orbital_pv-0.3.0/README.md

@@ -0,0 +1,151 @@
+# OrbitalPV
+
+Open-source full-stack lab for **spacecraft photovoltaic performance analytics**: PV physics, orbit/Sun geometry, real spacecraft data connectors, degradation/anomaly analytics, reproducible research labs, and a web application platform.
+
+The structure follows a modular separation-of-concerns approach: domain models, physics engines, connectors and analytics are independent workspace packages with consistent quality tooling.
+
+## Install from PyPI
+
+```bash
+python -m pip install orbital-pv
+```
+
+Use the public API as:
+
+```python
+import orbitalpv as opv
+
+positions_m = opv.circular_orbit_positions_m(
+    altitude_m=550_000.0,
+    inclination_deg=51.6,
+)
+
+g_am0 = opv.am0_irradiance(opv.ASTRONOMICAL_UNIT_M)
+```
+
+Optional extras:
+
+```bash
+python -m pip install "orbital-pv[examples]"
+python -m pip install "orbital-pv[orbit]"
+python -m pip install "orbital-pv[full]"
+```
+
+## Foundation stack
+
+- **pvlib** — tested PV equations and I-V/single-diode reference models behind a space-specific adapter.
+- **Skyfield + python-sgp4** — Earth-orbit catalog propagation from CCSDS OMM/TLE.
+- **Astropy** — time, units, frames and baseline solar-system coordinates.
+- **SpiceyPy / NASA SPICE** — mission-grade ephemeris, attitude, clocks and frame transforms.
+- **SpacePy / later radiation engines** — radiation/environment workstream.
+- **HTTP connectors** — CelesTrak, Space-Track, NASA SSCWeb, NAIF, CDAWeb/HAPI, NOAA SWPC, SatNOGS DB and BIRDS EPS.
+
+`poliastro` is intentionally not a core dependency because its upstream repository is archived.
+
+## Repository map
+
+```text
+orbital-pv/
+├── src/orbitalpv/                 # public PyPI API
+├── apps/
+│   ├── space-pv-cli/
+│   ├── space-pv-api/
+│   └── space-pv-web/
+├── packages/
+│   ├── space-pv-core/
+│   ├── space-pv-orbit/
+│   ├── space-pv-pvmodel/
+│   ├── space-pv-space-env/
+│   ├── space-pv-connectors/
+│   ├── space-pv-analytics/
+│   ├── space-pv-storage/
+│   └── space-pv-orchestration/
+├── examples/
+├── labs/
+├── data/{raw,bronze,silver,gold}/
+├── docs/
+└── tests/
+```
+
+The `space_pv_*` packages remain available as lower-level implementation modules for contributors and advanced use, while `orbitalpv` is the stable user-facing import.
+
+## Documentation
+
+**https://julianascencio.github.io/orbital-pv/**
+
+The documentation uses Sphinx, PyData Sphinx Theme, and Sphinx-Gallery. Gallery examples execute during the documentation build and use the same `orbitalpv` API installed from PyPI.
+
+Build locally:
+
+```bash
+make docs
+```
+
+## Development
+
+```bash
+uv sync --all-packages --group dev --group lab --group orbit --group pv --group space --group app
+uv run pytest
+uv run ruff check .
+uv run ty check
+```
+
+## Science pipeline
+
+```text
+real orbit/telemetry/environment data
+              |
+              v
+      canonical time + frames
+              |
+    +---------+----------+
+    |                    |
+orbit + Sun          PV telemetry
+    |                    |
+    v                    |
+eclipse + AOI + AM0      |
+    |                    |
+    +----------+---------+
+               v
+      expected PV performance
+               |
+               v
+       residual / degradation
+               |
+               v
+      anomaly + EOL analytics
+```
+
+See `docs/foundation_stack.md`, `docs/connectors/catalog.md`, `docs/architecture.md` and `docs/state_of_art.md`.
+
+## Application platform
+
+The web/application layer is intentionally separated from the scientific packages:
+
+- **React + TypeScript + Vite** — frontend application.
+- **FastAPI** — API and job submission boundary.
+- **PostgreSQL** — durable multi-user/transactional application state and job metadata.
+- **DuckDB** — local analytics, parquet-backed research datasets and fast time-series exploration.
+- **Celery + Redis** — long-running ingestion, orbit, PV and analytics jobs.
+- **Flower** — local Celery worker/task observability.
+
+Start the development stack with:
+
+```bash
+docker compose up --build
+```
+
+Then open React on `http://localhost:5173`, FastAPI docs on `http://localhost:8000/docs`, and Flower on `http://localhost:5555`.
+
+## Space GIS and dynamic visualization
+
+The platform separates scientific orbital reference-frame state from Earth-fixed GIS render products. PostGIS serves hot satellite positions, ground tracks, stations and footprints; DuckDB/Parquet retain analytical history and chart rollups; CesiumJS renders time-dynamic 3D orbital scenes. See `docs/space_gis_and_visualization.md`.
+
+## Literature library
+
+A curated, source-tagged literature library is maintained in [`docs/literature/`](docs/literature/README.md). It covers the 2026 state of the art in space-PV cells and arrays, mission-aware performance modelling, radiation/degradation, digital twins, telemetry/AI, and open flight datasets/APIs.
+
+## Roadmap evidence
+
+- `docs/literature/09_ieso_2026_workshop_roadmap.md` — 2026 IESO workshop targets translated into repository features and R&D priorities.
+- `docs/product_feature_roadmap.md` — prioritized product epics derived from the literature and 2026 IESO workshop.

orbital_pv-0.3.0/apps/space-pv-api/src/space_pv_api/__init__.py

@@ -0,0 +1 @@
+"""Space PV HTTP API."""

orbital_pv-0.3.0/apps/space-pv-api/src/space_pv_api/config.py

@@ -0,0 +1,13 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class APISettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="SPACE_PV_", env_file=".env", extra="ignore")
+
+    api_host: str = "0.0.0.0"
+    api_port: int = 8000
+    cors_origins: str = "http://localhost:5173"
+
+    @property
+    def allowed_origins(self) -> list[str]:
+        return [origin.strip() for origin in self.cors_origins.split(",") if origin.strip()]

orbital_pv-0.3.0/apps/space-pv-api/src/space_pv_api/main.py

@@ -0,0 +1,202 @@
+import math
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime, timedelta
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+
+from space_pv_orchestration.celery_app import celery_app
+from space_pv_storage import (
+    Base,
+    JobRun,
+    attach_celery_task,
+    create_engine_from_settings,
+    create_job,
+    get_track_samples,
+    list_jobs,
+    list_latest_satellite_states,
+    session_factory,
+)
+
+from .config import APISettings
+from .schemas import (
+    JobAccepted,
+    JobCreate,
+    JobRead,
+    MapSatelliteState,
+    MapScene,
+    MapTrack,
+    OrbitSample,
+)
+
+settings = APISettings()
+engine = create_engine_from_settings()
+SessionLocal = session_factory()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    # Development bootstrap. Replace with Alembic migrations before production.
+    Base.metadata.create_all(engine)
+    yield
+
+
+app = FastAPI(
+    title="Space PV Analytics API",
+    version="0.1.0",
+    description="API for satellite ingestion, orbit/PV computations and analytics jobs.",
+    lifespan=lifespan,
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok", "service": "space-pv-api"}
+
+
+@app.post("/api/v1/jobs", response_model=JobAccepted, status_code=202)
+def submit_job(request: JobCreate) -> JobAccepted:
+    with SessionLocal() as session:
+        job = create_job(session, request.job_type, request.payload)
+        task = celery_app.send_task(
+            "space_pv.analytics.execute",
+            args=[job.id, request.job_type, request.payload],
+            queue="analytics",
+        )
+        attach_celery_task(session, job, task.id)
+        return JobAccepted(job_id=job.id, task_id=task.id, job_type=request.job_type)
+
+
+def _job_to_schema(job: JobRun) -> JobRead:
+    return JobRead(
+        id=job.id,
+        task_name=job.task_name,
+        celery_task_id=job.celery_task_id,
+        status=job.status.value,
+        payload=job.payload,
+        result=job.result,
+        error=job.error,
+        created_at=job.created_at,
+        started_at=job.started_at,
+        finished_at=job.finished_at,
+    )
+
+
+@app.get("/api/v1/jobs", response_model=list[JobRead])
+def jobs(limit: int = 100) -> list[JobRead]:
+    with SessionLocal() as session:
+        return [_job_to_schema(job) for job in list_jobs(session, min(max(limit, 1), 500))]
+
+
+@app.get("/api/v1/jobs/{job_id}", response_model=JobRead)
+def get_job(job_id: str) -> JobRead:
+    with SessionLocal() as session:
+        job = session.get(JobRun, job_id)
+        if job is None:
+            raise HTTPException(status_code=404, detail="Job not found")
+        return _job_to_schema(job)
+
+
+@app.get("/api/v1/map/satellites/latest", response_model=list[MapSatelliteState])
+def latest_satellite_map_states(limit: int = 2000) -> list[MapSatelliteState]:
+    with SessionLocal() as session:
+        rows = list_latest_satellite_states(session, min(max(limit, 1), 10000))
+    return [MapSatelliteState(**row) for row in rows]
+
+
+@app.get("/api/v1/map/satellites/{satellite_id}/track", response_model=MapTrack)
+def satellite_track(
+    satellite_id: str,
+    start: datetime,
+    end: datetime,
+    lod: int = 1,
+) -> MapTrack:
+    if end <= start:
+        raise HTTPException(status_code=400, detail="end must be after start")
+    with SessionLocal() as session:
+        segments = get_track_samples(session, satellite_id, start, end, lod)
+    if not segments:
+        raise HTTPException(status_code=404, detail="No cached track for requested window")
+
+    samples: list[OrbitSample] = []
+    for segment in segments:
+        epoch = segment["start_at"]
+        for offset_s, lon, lat, altitude_m in segment["samples"]:
+            timestamp = epoch + timedelta(seconds=float(offset_s))
+            if start <= timestamp <= end:
+                samples.append(
+                    OrbitSample(
+                        timestamp=timestamp,
+                        longitude_deg=float(lon),
+                        latitude_deg=float(lat),
+                        altitude_m=float(altitude_m),
+                    )
+                )
+    return MapTrack(
+        satellite_id=satellite_id,
+        name=satellite_id,
+        source=str(segments[0]["source"]),
+        samples=samples,
+    )
+
+
+def _demo_track(
+    name: str,
+    inclination_deg: float,
+    altitude_m: float,
+    phase_deg: float,
+    epoch: datetime,
+) -> MapTrack:
+    """Visual-only deterministic samples used to validate the Cesium pipeline.
+
+    These are deliberately not presented as propagated ephemerides. Real tracks come
+    from space-pv-orbit and are cached in gis.orbit_track_segments.
+    """
+    period_s = 95.0 * 60.0
+    samples: list[OrbitSample] = []
+    for offset_s in range(0, 2 * 60 * 60 + 1, 30):
+        theta = 2.0 * math.pi * offset_s / period_s + math.radians(phase_deg)
+        latitude = inclination_deg * math.sin(theta)
+        longitude = ((math.degrees(theta) * 0.78 + phase_deg + 180.0) % 360.0) - 180.0
+        samples.append(
+            OrbitSample(
+                timestamp=epoch + timedelta(seconds=offset_s),
+                longitude_deg=longitude,
+                latitude_deg=latitude,
+                altitude_m=altitude_m,
+            )
+        )
+    return MapTrack(
+        satellite_id=name.lower().replace(" ", "-"),
+        name=name,
+        source="visual_demo",
+        samples=samples,
+    )
+
+
+@app.get("/api/v1/map/demo", response_model=MapScene)
+def demo_map_scene() -> MapScene:
+    epoch = datetime.now(UTC).replace(microsecond=0)
+    return MapScene(
+        generated_at=epoch,
+        tracks=[
+            _demo_track("Demo LEO 51.6", 51.6, 420_000.0, 0.0, epoch),
+            _demo_track("Demo SSO 97.4", 82.0, 550_000.0, 115.0, epoch),
+            _demo_track("Demo LEO 35", 35.0, 650_000.0, 235.0, epoch),
+        ],
+    )
+
+
+def run() -> None:
+    import uvicorn
+
+    uvicorn.run(
+        "space_pv_api.main:app", host=settings.api_host, port=settings.api_port, reload=False
+    )

orbital_pv-0.3.0/apps/space-pv-api/src/space_pv_api/schemas.py

@@ -0,0 +1,61 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class JobCreate(BaseModel):
+    job_type: str = Field(min_length=1, max_length=200)
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class JobAccepted(BaseModel):
+    job_id: str
+    task_id: str
+    job_type: str
+    status: str = "queued"
+
+
+class JobRead(BaseModel):
+    id: str
+    task_name: str
+    celery_task_id: str | None
+    status: str
+    payload: dict[str, Any]
+    result: dict[str, Any] | None
+    error: str | None
+    created_at: datetime
+    started_at: datetime | None
+    finished_at: datetime | None
+
+
+class MapSatelliteState(BaseModel):
+    satellite_id: str
+    name: str
+    norad_id: int | None = None
+    observed_at: datetime
+    longitude_deg: float
+    latitude_deg: float
+    altitude_m: float
+    illumination_fraction: float | None = None
+    pv_power_w: float | None = None
+    source: str
+
+
+class OrbitSample(BaseModel):
+    timestamp: datetime
+    longitude_deg: float
+    latitude_deg: float
+    altitude_m: float
+
+
+class MapTrack(BaseModel):
+    satellite_id: str
+    name: str
+    source: str
+    samples: list[OrbitSample]
+
+
+class MapScene(BaseModel):
+    generated_at: datetime
+    tracks: list[MapTrack]