Mm rework lingfeng into Dev

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+# Build the Sphinx docs and publish them to GitHub Pages.
+#
+# This is an ad-free mirror of the Read the Docs build, not a replacement:
+# RTD still provides the per-branch versions (/en/<branch>/) and rebuilds on
+# every push. GitHub Pages serves a single site per repository, so this
+# publishes one version -- the branch this workflow runs on.
+#
+# Before the first run, enable Pages on the repository:
+#   Settings -> Pages -> Build and deployment -> Source: "GitHub Actions"
+# That needs repo admin. The site then appears at
+#   https://<owner>.github.io/<repo>/
+#
+# Note the docs build never imports flystar (sphinx-autoapi reads the source
+# statically), so the science stack is deliberately not installed here.
+
+name: docs
+
+on:
+  push:
+    branches: [mm_rework_lingfeng]
+    paths:
+      - 'docs/**'
+      - 'flystar/**'
+      - '.readthedocs.yaml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Let a newer run supersede an in-flight one, but never cancel a deploy midway.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install documentation requirements
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r docs/requirements.txt
+
+      - name: Build HTML
+        run: |
+          python -m sphinx -b html -W --keep-going docs docs/_build/html
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,79 @@
+# Build the distributions and publish them to PyPI.
+#
+# Authentication is PyPI Trusted Publishing (OpenID Connect), so there is no
+# API token to store or rotate: PyPI verifies the workflow's identity directly.
+# That needs a one-time setup on PyPI, under the project's
+# Publishing -> Add a new pending publisher:
+#
+#   PyPI project name : flystar
+#   Owner             : MovingUniverseLab
+#   Repository        : flystar
+#   Workflow name     : publish.yml
+#   Environment       : pypi
+#
+# Publishing is triggered by publishing a GitHub Release, not by pushing a tag,
+# so creating the tag stays a reversible act and the upload takes a deliberate
+# second step. The version comes from the tag via setuptools_scm, so the tag is
+# what decides the version that is uploaded -- and a version can never be
+# re-uploaded to PyPI, so it is worth being sure of.
+
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:        # manual run, for a TestPyPI dry run
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0        # setuptools_scm needs the tags to find the version
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+      - name: Show what will be uploaded
+        run: ls -l dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    # Manual runs go to TestPyPI, so the whole path can be rehearsed without
+    # burning a version number on PyPI proper.
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,3 +1,7 @@
+*.png
+*random*.fits
+*random*.lis
+*.DS_Store
 *.pyc
 .ipynb_checkpoints/
 
@@ -66,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api/
 
 # PyBuilder
 target/
@@ -106,3 +111,14 @@ ENV/
 # mypy
 .mypy_cache/
 
+docs/jupyter_execute/
+
+# Documentation figures are generated by docs/make_example_figures.py but are
+# committed, so the docs build needs no science stack. Exempt them from the
+# blanket *.png rule above.
+!docs/_static/*.png
+
+# Written at build time by setuptools_scm (see setup.py use_scm_version).
+# Tracking it makes every build dirty the tree, which appends a ".d<date>"
+# suffix to the version -- including on tagged release builds.
+flystar/version.py

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# flystar itself is deliberately NOT installed here. The API reference is
+# generated by sphinx-autoapi from the source tree via static analysis, so the
+# package never has to be imported and its science-stack dependencies
+# (numpy/scipy/astropy/matplotlib) don't need to resolve for a docs build to
+# succeed.
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+formats:
+  - htmlzip

CHANGES.rst

@@ -0,0 +1,72 @@
+=========
+Changelog
+=========
+
+Unreleased
+==========
+
+API changes to ``MosaicSelfRef`` and ``MosaicToRef``
+----------------------------------------------------
+
+- ``dr_tol`` is now a required argument, given before the optional ones.
+  Matching is a radius search, so there is no meaningful default: the old
+  ``dr_tol=[1.0]`` silently applied a one-unit radius in whatever units the
+  reference frame happened to use.
+- The ``iters`` argument is gone. It had never been read -- the iteration
+  count has always come from the length of ``dr_tol`` -- so calls that passed
+  a disagreeing ``iters`` were already running the ``dr_tol`` schedule. Drop
+  it from the call.
+- The number of iterations is now the length of the longest schedule given:
+  ``dr_tol``, ``dm_tol``, ``outlier_tol`` or ``trans_args``. Any of them may
+  be a single value, broadcast to that length, so ``dr_tol=0.5,
+  dm_tol=[1.0, 0.5]`` is two passes at a constant radius, and all single
+  values is a single pass. Two schedules of differing length remain an error.
+  ``mag_lim`` does not take part -- its ``[min, max]`` form is a pair, not a
+  schedule -- and is still checked against the resulting count.
+- ``dm_tol`` now defaults to ``None``, which places no magnitude cut on the
+  match. The old default of ``[1.0]`` rejected pairs more than one magnitude
+  apart, which is wrong across filters and arbitrary within one.
+- ``trans_args`` now carries a per-starlist axis as well as a per-iteration
+  one, and is normalized to ``(N_iters, N_lists)``. It accepts a bare dict, a
+  flat list of ``N_iters`` dicts, or a nested ``(N_iters, N_lists)`` list, so
+  one epoch can be given a different transformation order from the rest. As
+  with ``mag_lim``, a single axis indexes iterations, so existing calls keep
+  working unchanged; per-list arguments use the nested form, a single
+  iteration of them being ``[[...]]``.
+- ``calc_bootstrap_errors`` now re-fits with the whole ``trans_args`` dict from
+  the last iteration. It had been reaching for ``trans_args[0]['order']``,
+  which took the *first* iteration's order -- bootstrapping a rising-order
+  schedule at the loose starting order rather than the one the fit converged
+  with -- and dropped every other key.
+
+0.1.0 (2026-08-26)
+==================
+
+First release on PyPI.
+
+FlyStar cross-matches and aligns stellar astrometry catalogues. It derives
+the transformations between a stack of starlists and a common reference
+frame, matches stars across them, and fits a motion model per star
+(``Empty``, ``Fixed``, ``Linear``, ``Acceleration`` or ``Parallax``).
+
+``MosaicSelfRef`` builds the reference frame from the starlists themselves;
+``MosaicToRef`` aligns them to an external catalogue such as Gaia.
+
+Notes for this release
+----------------------
+
+- The reference table records each star's identity in each starlist as
+  ``idx_in_list``, an integer index into that starlist, rather than as a copy
+  of the name. Use :func:`flystar.align.names_in_list` to recover the names.
+  Tables written by pre-release versions of the code carry a string
+  ``name_in_list`` column instead; ``flystar.plots`` and ``flystar.analysis``
+  read either.
+- ``jplephem`` is a hard requirement, not an extra: astropy uses it whenever a
+  solar-system ephemeris is evaluated, which the ``Parallax`` motion model
+  does.
+- ``shapely``, ``astroquery`` and ``plotly`` are imported lazily by the
+  features that need them (polygon footprints for the initial guess, Gaia and
+  JPL Horizons queries, and interactive diagnostic plots respectively). Install
+  them with ``pip install flystar[optional]``.
+- Tests are not included in the distributions; run them from a checkout of the
+  repository.

MANIFEST.in

@@ -1,17 +1,21 @@
 include README.rst
 include CHANGES.rst
-include setup.cfg
-include LICENSE.rst
 include pyproject.toml
-
-recursive-include flystar *.pyx *.c *.pxd
-recursive-include docs *
+include setup.cfg
 recursive-include licenses *
-recursive-include cextern *
-recursive-include scripts *
+
+# Documentation sources, but not the example data: docs/examples carries ~10 MB
+# of .lis/.fits inputs for the Gaia notebook, which Read the Docs takes from the
+# repository rather than from an sdist.
+recursive-include docs *.rst *.py *.ipynb *.txt Makefile make.bat
+recursive-include docs/_static *
+prune docs/examples/flystar_mosaic_to_gaia
+
+# Tests are not distributed -- see the packages.find exclude in pyproject.toml.
+prune flystar/tests
 
 prune build
 prune docs/_build
 prune docs/api
 
-global-exclude *.pyc *.o
+global-exclude *.pyc *.pyo *.o __pycache__

README.rst

@@ -5,6 +5,51 @@ FlyStar
     :target: http://www.astropy.org
     :alt: Powered by Astropy Badge
 
+FlyStar aligns many star lists into one common frame and fits each star's motion
+there, choosing per star from a set of motion models. It cross-matches the stars
+across every list, solves for the transformation that carries each list into a
+common reference frame, and fits positions, proper motions and where wanted
+parallaxes, with uncertainties.
+
+Documentation
+-------------
+
+Two builds of the same source, both from the ``mm_rework_lingfeng`` branch:
+
+* **Read the Docs** -- https://flystar.readthedocs.io/en/mm_rework_lingfeng/
+  Rebuilt on every push, and keeps a version per branch under ``/en/<branch>/``.
+  Note that ``/en/latest/`` tracks the default branch, which does not have these
+  pages.
+* **GitHub Pages** -- https://wei-lingfeng.github.io/flystar/
+  An ad-free mirror of the same build. One version only: whatever
+  ``mm_rework_lingfeng`` last published.
+
+Start on either front page: it installs FlyStar and then builds a synthetic
+four-epoch data set, aligns it, and checks the recovered positions and proper
+motions against the truth that went in.
+
+.. warning::
+
+   These describe the ``mm_rework_lingfeng`` branch, whose motion-model
+   framework does not exist on ``main``. The API reference on both sites is
+   generated from this branch's source.
+
+Installation
+------------
+
+Not on PyPI; install from the repository::
+
+    git clone https://github.com/MovingUniverseLab/flystar.git
+    cd flystar
+    pip install -e .
+
+That pulls in numpy, scipy, astropy, matplotlib, pandas, joblib and tqdm, all of
+which the package imports at module level. Python 3.7 or newer. Three further
+packages are imported lazily and only needed for the features that use them --
+``shapely``, ``astroquery`` and ``plotly`` -- grouped as an extra::
+
+    pip install -e '.[optional]'
+
 
 License
 -------
@@ -21,29 +66,3 @@ Contributing
 
 We love contributions! FlyStar is open source,
 built on open source, and we'd love to have you hang out in our community.
-
-**Imposter syndrome disclaimer**: We want your help. No, really.
-
-There may be a little voice inside your head that is telling you that you're not
-ready to be an open source contributor; that your skills aren't nearly good
-enough to contribute. What could you possibly offer a project like this one?
-
-We assure you - the little voice in your head is wrong. If you can write code at
-all, you can contribute code to open source. Contributing to open source
-projects is a fantastic way to advance one's coding skills. Writing perfect code
-isn't the measure of a good developer (that would disqualify all of us!); it's
-trying to create something, making mistakes, and learning from those
-mistakes. That's how we all improve, and we are happy to help others learn.
-
-Being an open source contributor doesn't just mean writing code, either. You can
-help out by writing documentation, tests, or even giving feedback about the
-project (and yes - that includes giving feedback about the contribution
-process). Some of these contributions may be the most valuable to the project as
-a whole, because you're coming to the project with fresh eyes, so you can see
-the errors and assumptions that seasoned contributors have glossed over.
-
-Note: This disclaimer was originally written by
-`Adrienne Lowe <https://github.com/adriennefriend>`_ for a
-`PyCon talk <https://www.youtube.com/watch?v=6Uj746j9Heo>`_, and was adapted by
-FlyStar based on its use in the README file for the
-`MetPy project <https://github.com/Unidata/MetPy>`_.