csar 0.1.1__tar.gz

csar-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    # Non-editable so `uv sync` builds + installs csar as the wheel ships it
+    # (no meson-python rebuild-on-import hook, which needs build isolation off).
+    env:
+      UV_NO_EDITABLE: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache-suffix: test
+
+      - uses: extractions/setup-just@v4
+
+      - name: Install
+        run: uv sync
+
+      - name: Test + coverage
+        run: just ci-test

csar-0.1.1/.github/workflows/wheels.yml

@@ -0,0 +1,172 @@
+name: wheels
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+
+concurrency:
+  group: wheels-${{ github.ref }}
+  # Don't cancel a release run mid-publish, but for branch pushes and
+  # PRs the latest commit should win — old runs just block the queue.
+  cancel-in-progress: ${{ github.event_name != 'release' }}
+
+jobs:
+  sdist:
+    name: build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.13"
+          cache-suffix: wheels-sdist
+
+      - name: Build sdist
+        run: uv build --sdist
+
+      - name: Test sdist round-trip
+        run: |
+          uv venv test-env
+          uv pip install --python test-env/bin/python --no-cache dist/*.tar.gz pytest numpy
+          test-env/bin/pytest -o addopts=
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          compression-level: 0
+
+  # Ask cibuildwheel which wheels it would build for each (platform,
+  # arch) given our [tool.cibuildwheel] config, then emit a JSON
+  # matrix that the wheels job consumes via `fromJson()`. Saves
+  # hand-maintaining a 30-row include list as Python versions evolve.
+  discover:
+    name: discover build identifiers
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      # Keep this version in sync with `pypa/cibuildwheel@vX.Y.Z`
+      # below — GHA's `uses:` doesn't accept expression interpolation,
+      # so the literal has to live in two places.
+      - run: pip install cibuildwheel==3.4.1
+      - id: set
+        shell: bash
+        run: |
+          python <<'PY' >> $GITHUB_OUTPUT
+          import json
+          import subprocess
+
+          # (runner image, cibuildwheel platform name, arch).
+          targets = [
+              ("ubuntu-latest",    "linux",   "x86_64"),
+              ("ubuntu-24.04-arm", "linux",   "aarch64"),
+              ("macos-latest",     "macos",   "arm64"),
+              ("windows-latest",   "windows", "AMD64"),
+          ]
+
+          include = []
+          for runner, platform, arch in targets:
+              ids = subprocess.run(
+                  ["cibuildwheel",
+                   f"--platform={platform}",
+                   f"--archs={arch}",
+                   "--print-build-identifiers"],
+                  capture_output=True, text=True, check=True,
+              ).stdout.split()
+              for ident in ids:
+                  include.append({"os": runner, "only": ident})
+
+          print(f"matrix={json.dumps({'include': include})}")
+          PY
+
+  wheels:
+    # One job per build identifier (matrix expanded from `discover`)
+    # so wall-clock approaches max(per-wheel build time) instead of
+    # sum. Free for public repos on GitHub Actions runner-minutes.
+    name: ${{ matrix.only }}
+    needs: discover
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover.outputs.matrix) }}
+
+    steps:
+      - uses: actions/checkout@v6
+
+      # cibuildwheel uses uv as the build frontend; on Linux it
+      # bootstraps uv inside the manylinux container, but on macOS /
+      # Windows it expects uv on the host PATH. Skip the host install
+      # on Linux jobs — saves ~5s × N Linux runners of runner-minutes.
+      - if: runner.os != 'Linux'
+        uses: astral-sh/setup-uv@v8.1.0
+
+      # Pin uv's cache to C: on Windows so hardlinks work.
+      #
+      # setup-uv defaults UV_CACHE_DIR to ${RUNNER_TEMP}/setup-uv-cache,
+      # which on GitHub-hosted Windows runners is D:\a\_temp\... .
+      # cibuildwheel's `build[uv]` frontend creates Python's isolated
+      # build env via tempfile.gettempdir(), which on Windows resolves
+      # to C:\Users\runneradmin\AppData\Local\Temp\... . NTFS doesn't
+      # support hardlinks across drives, so uv falls back to full file
+      # copy ("Failed to hard link ... os error 17; falling back to
+      # copy"). For build-isolation envs containing a chunky toolchain
+      # like ziglang (~50MB, hundreds of small files, PE binaries that
+      # Defender deep-scans), that's ~48s per wheel install vs ~8s
+      # when hardlinking works.
+      #
+      # Pinning UV_CACHE_DIR to %LOCALAPPDATA% (always on C:) puts the
+      # cache on the same drive as the build env and restores
+      # hardlinking.
+      #
+      # Tracking upstream (acknowledged but not fixed; eifinger himself
+      # tried in setup-uv#451 and reverted in #460):
+      #   https://github.com/astral-sh/setup-uv/issues/227
+      #   https://github.com/astral-sh/setup-uv/issues/371
+      #   https://github.com/astral-sh/setup-uv/pull/451
+      - if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $cache = Join-Path $env:LOCALAPPDATA 'uv-cache'
+          "UV_CACHE_DIR=$cache" | Out-File -FilePath $env:GITHUB_ENV -Append
+
+      - uses: pypa/cibuildwheel@v3.4.1
+        with:
+          only: ${{ matrix.only }}
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: wheels-${{ matrix.only }}
+          path: wheelhouse/*.whl
+          compression-level: 0
+
+  # Publish to PyPI on a published GitHub release, via OIDC trusted
+  # publishing (no API tokens). Gated by the `pypi` environment configured
+  # on this repo. Runs only on release:published, so pushes/PRs never upload.
+  to-pypi:
+    name: publish to PyPI
+    needs: [sdist, wheels]
+    if: github.event_name == 'release' && github.event.action == 'published'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/csar
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          pattern: "{wheels-*,sdist}"
+          merge-multiple: true
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

csar-0.1.1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Bundled static library (produced by the zig build)
+src/csar/libcsar.*
+
+# Zig build artifacts
+zig-out/
+.zig-cache/
+zig-pkg/
+
+# uv lockfile — opt in if you want it tracked
+uv.lock
+
+# Script outputs (generated plots), at any depth (incl. explorations/out/)
+scripts/**/out/
+
+# OS
+.DS_Store
+.ipynb_checkpoints/

csar-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AJ Friend
+
+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.

csar-0.1.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: csar
+Version: 0.1.1
+Summary: Conic spherical aspect-ratio solver: tightest enclosing cone of a point set on the unit sphere.
+Keywords: conic,spherical,aspect-ratio,cone,geometry,geodesy,geospatial,optimization,zig
+Author-Email: AJ Friend <ajfriend@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Zig
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Project-URL: Homepage, https://github.com/ajfriend/csar_py
+Project-URL: Repository, https://github.com/ajfriend/csar_py
+Project-URL: Issues, https://github.com/ajfriend/csar_py/issues
+Project-URL: Upstream Zig package, https://github.com/ajfriend/csar_zig
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3; extra == "plot"
+Description-Content-Type: text/markdown
+
+# csar: Conic Spherical Aspect Ratio
+
+Python bindings for [`csar_zig`](https://github.com/ajfriend/csar_zig),
+a spherical aspect-ratio solver. Given a point set on the unit sphere,
+it finds the tightest ellipsoidal cone enclosing the points and returns
+the cone's axis ratio.
+
+A thin Cython binding over a small C-ABI shim that links the upstream
+`csar` Zig package as a static archive — no separate shared library
+ships in the wheel.
+
+## Install
+
+Not on PyPI yet — install directly from GitHub. Point pip/uv at the git
+URL, either the latest `main` or a tagged release:
+
+```sh
+# latest main
+pip install git+https://github.com/ajfriend/csar_py.git
+uv pip install git+https://github.com/ajfriend/csar_py.git
+
+# a specific tagged release
+pip install git+https://github.com/ajfriend/csar_py.git@v0.1.0
+uv pip install git+https://github.com/ajfriend/csar_py.git@v0.1.0
+```
+
+For the optional plotting helper (`csar.plot_cone`), add the `plot` extra:
+
+```sh
+pip install "csar[plot] @ git+https://github.com/ajfriend/csar_py.git"
+```
+
+That path triggers a source build: meson-python pulls the Zig toolchain
+from the `ziglang` PyPI wheel (`python -m ziglang build`), compiles the
+upstream `csar_zig` package into a static archive — fetched over the
+network from the URL pinned in `src/zig/build.zig.zon` — then cythonizes
+`src/cython/_cy.pyx` and links the result against it. No host-level Zig
+or Cython install is required (Python 3.11+).
+
+### Local development
+
+```sh
+just test       # reinstall + run the test suite
+just reinstall  # force a clean rebuild of the Zig extension
+```
+
+## Usage
+
+```python
+import csar
+
+# A sequence of points. Each point is (lat, lng) in degrees by
+# default; pass geo='vec3' to give unit (x, y, z) triples instead.
+pts = [
+    (0.0,  0.0),
+    (0.0, 90.0),
+    (90.0, 0.0),
+]
+
+r = csar.solve(pts)
+if isinstance(r, csar.Converged):
+    print(r.aspect_ratio)  # cross-section axis ratio (>= 1)
+    print(r.Q[:, 0])       # unit cone axis (x, y, z) — first column of Q
+```
+
+Any list/tuple of points works; a NumPy array is also accepted and is
+read as an `(N, k)` array whose **rows are points** (`k` = 2 for the
+`latlng`/`lonlat` families, 3 for `'vec3'`). The `geo` argument picks
+the convention: `'latlng'` (default, h3's `(lat, lng)` order),
+`'lonlat'` (GeoJSON's `(lon, lat)` order), their `_deg`/`_rad`
+variants, or `'vec3'`.
+
+Objects implementing `__geo_interface__` (shapely, geopandas, geojson,
+h3 `LatLngPoly`/`LatLngMultiPoly`, …) can be passed directly — their
+vertices are read as GeoJSON `(lon, lat)` degrees, so `geo` is ignored:
+
+```python
+import geopandas as gpd
+
+gdf = gpd.read_file('countries.geojson')
+for name, geom in zip(gdf['ADMIN'], gdf.geometry):
+    r = csar.solve(geom)            # shapely geometry via __geo_interface__
+    if isinstance(r, csar.Converged):
+        print(name, r.aspect_ratio)
+```
+
+`MultiPoint`, `LineString`, `Polygon` (exterior ring), `MultiPolygon`,
+and a `Feature` wrapping one of those are supported.
+
+To visualize the fit, `csar.plot_cone(result, geom)` draws the outline
+gnomonic-projected at the cone axis with the enclosing ellipse overlaid
+— defaulting to north-up, scaled to metres, with labelled axes (needs
+matplotlib — `pip install csar[plot]`):
+
+```python
+csar.plot_cone(r, geom, title='Chile')  # a finished figure from one call
+```
+
+`scripts/states/` and `scripts/countries/` are full end-to-end examples.
+
+`solve` runs all of this through `csar.to_vec3(points, geo=...)`, which
+returns the `(N, 3)` array of unit vectors the solver actually sees.
+Call it directly to inspect how your input maps onto the sphere:
+
+```python
+csar.to_vec3([(0, 0), (0, 90), (90, 0)])
+# array([[1., 0., 0.],
+#        [0., 1., 0.],
+#        [0., 0., 1.]])
+```
+
+## Outcomes
+
+`solve` returns one of three outcome types — `Converged`, `Infeasible`,
+or `DidNotConverge` (collectively `Outcome`) — mirroring the Zig
+`Outcome` tagged union. Each carries **only** the fields meaningful for
+its outcome, so you dispatch on the type rather than guarding nullable
+fields:
+
+```python
+match csar.solve(pts):
+    case csar.Converged() as c:
+        use(c.aspect_ratio, c.Q)      # certified cone
+    case csar.Infeasible() as i:
+        handle(i.residual)            # no enclosing cone exists
+    case csar.DidNotConverge() as d:
+        retry(d.gap, d.outer_iters)   # hit the iteration cap
+```
+
+On a `Converged`, `sigma` is the `(3,)` eigenvalue array and `Q` the
+`(3, 3)` eigenbasis (column `i` pairs with `sigma[i]`; column 0 is the
+axis), so the enclosing ellipsoid matrix is
+`A = c.Q @ np.diag(c.sigma) @ c.Q.T`. `DidNotConverge` exposes the same
+`sigma`/`Q`/`gap` for diagnostics but, being uncertified, deliberately
+has no `aspect_ratio`. See the docstrings in `src/csar/__init__.py` for
+the full field reference.
+
+## Solver paths
+
+`solve` picks its solver via `method=`: `'auto'` (the default) resolves
+to the library's recommended method — currently `'trust'`, a
+trust-region descent that converges on every input family constructed
+to date, including the wide/elongated inputs the original solver
+structurally cannot. `'alternating'` is that original solver, kept for
+continuity and for large dense near-circular inputs where it can still
+be faster. The outcome's `.method` records the concrete path that ran.
+
+## Layout
+
+```
+.
+├── pyproject.toml          — meson-python config, package metadata
+├── meson.build             — drives Zig static-archive build + Cython compile
+├── justfile                — reinstall / test / wheel / examples / clean
+├── src/
+│   ├── cython/_cy.pyx      — Cython binding, exposes _cy.solve
+│   ├── csar/
+│   │   ├── __init__.py     — gathers the public API (solve, to_vec3, plot_cone, Outcome…)
+│   │   ├── convert.py      — input → (N, 3) unit vectors: to_vec3, geo-interface
+│   │   ├── outcomes.py     — Converged/Infeasible/DidNotConverge + build()
+│   │   ├── plot.py         — plot_cone (optional; needs matplotlib)
+│   │   └── solver.py       — solve(): convert → _cy.solve → build
+│   └── zig/
+│       ├── build.zig       — produces libcsar.{a,lib} (static archive)
+│       ├── build.zig.zon   — pins the csar_zig dependency
+│       └── c_api.zig       — pub export fn csar_solve
+├── scripts/                — examples (run via `just states|countries`)
+│   ├── states/             — US-state aspect ratios (geopandas + csar)
+│   └── countries/          — country aspect ratios (geopandas + csar)
+└── tests/test_bindings.py
+```
+
+## History
+
+`csar` was previously developed as
+[`skar_py`](https://github.com/ajfriend/skar_py) and forked into this fresh
+repository under a new name, since the `skar` name was already taken on PyPI.
+The `skar_py` repository is preserved as-is for its history and provenance.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

csar-0.1.1/changelog.md

@@ -0,0 +1,24 @@
+# Changelog
+
+Notable changes to csar. Terse by design — each entry points to the PR or
+commit that carries the full detail.
+
+## [0.1.1]
+
+- First PyPI release. Enable OIDC trusted-publishing upload in the `wheels`
+  workflow (`to-pypi` job, runs on a published GitHub release). No functional
+  change from 0.1.0 — the 0.1.0 tag predates the publish job, so this is the
+  first version pushed to PyPI.
+
+## [0.1.0]
+
+- Initial release of `csar` (conic spherical aspect ratio): Python bindings
+  for the [`csar_zig`](https://github.com/ajfriend/csar_zig) solver. Given a
+  point set on the unit sphere, `csar.solve` returns the tightest enclosing
+  ellipsoidal cone as a typed `Converged` / `Infeasible` / `DidNotConverge`
+  outcome; `method=` selects the solver path (`'auto'` default, resolving to
+  the trust-region method). Ships as a Cython extension with the upstream Zig
+  solver statically linked — no separate shared library in the wheel.
+  Continues the prototype previously developed as
+  [`skar_py`](https://github.com/ajfriend/skar_py), preserved as-is for its
+  history and provenance.