Skip to content

AGENTS.md

Latest commit

 

History

History
181 lines (143 loc) · 7.99 KB

AGENTS.md

File metadata and controls

181 lines (143 loc) · 7.99 KB
Raw

PyAutoCTI — Agent Instructions

Canonical, agent-agnostic instructions for this repo. CLAUDE.md imports this file; any tool that does not process @-imports should read this directly.

What this repo is

PyAutoCTI (package autocti) is a Bayesian library for calibrating and modelling Charge Transfer Inefficiency (CTI) in CCD imaging: charge-injection imaging (ImagingCI) and 1D datasets (Dataset1D), trap/CCD models clocked through the C++ arctic code (Clocker1D/Clocker2D wrapping arcticpy), FPR/EPER extraction (autocti/extract/), and per-dataset Fit*/Analysis* classes. Heritage: Euclid VIS CTI calibration; also HST ACS (autocti/instruments/acs).

Dependency direction: autocti may import autoarray (data structures), autofit (model-fitting), and autonerves (config). Nothing in the PyAuto stack imports autocti — it is a leaf like PyAutoLens.

Resurrection status (2026-07)

This repo was unmaintained for ~2 years and is being brought back into the ecosystem via the CTI resurrection epic (PyAutoCTI#82). Phase 0 (importable + unit tests green on the current stack) and Phase 1 (the visualization layer rewritten on the matplotlib function API, mirroring PyAutoGalaxy: per-domain plot/*_plots.py function modules, config-gated model/plotter.py orchestrators, autocti/util/plot_utils.py helpers) are complete, as is Phase 2 (autofit sync: multi-dataset fits and the aggregator run through af.AnalysisFactor/af.FactorGraphModel; the test suite has no skips). Remaining: Phase 3 CI + ecosystem plumbing, Phase 4 workspace update, Phase 5 workspace_test rebuild + release.

arcticpy (read before installing)

import autocti requires arcticpy (pinned 2.6), which is deliberately not a pip dependency:

  • Its PyPI sdist is source-only C++ — it needs libgsl-dev headers and a toolchain to build.
  • Its own requirements downgrade numpy below 2.0, breaking a modern stack.

So it is built with --no-build-isolation (reusing the numpy already present) and --no-deps (so it cannot drag numpy back down). Both flags have to be paid back by hand, and this is where installs go wrong:

  • --no-build-isolation means pip does not read arcticpy's build-system.requires, so every build dependency must already be installed. arcticpy declares none. Without setuptools the build fails with BackendUnavailable: Cannot import 'setuptools.build_meta' — and Python 3.12+ venvs no longer ship setuptools by default.
  • --no-deps means pip installs no runtime dependencies either. arcticpy/__init__.py imports read_noise, which imports scipy and matplotlib at import time, so without them a successful build still fails at import arcticpy with ModuleNotFoundError.

The full recipe:

sudo apt-get update && sudo apt-get install -y libgsl-dev
pip install --upgrade pip setuptools wheel   # BUILD deps: --no-build-isolation
pip install numpy cython                     #   will not supply these
pip install scipy matplotlib                 # RUNTIME deps --no-deps suppresses
pip install arcticpy==2.6 --no-build-isolation --no-deps

Verify with the distribution metadata, not arcticpy.__version__ — arcticpy exposes no such attribute, so that raises AttributeError even on a healthy install:

python -c "import arcticpy; from importlib.metadata import version; print(version('arcticpy'))"

This recipe has one owner for the whole organism: PyAutoHeart/.github/actions/install-arcticpy, the composite action every CTI repo's CI consumes. It also holds the single arcticpy==2.6 pin — bump it there, not here. Keep this note and that action in step.

If GSL headers are missing and you lack root, extract them locally (apt-get download libgsl-dev && dpkg -x ...) and point CPPFLAGS/LDFLAGS at them.

Quick commands

pip install -e ".[dev]"                                  # install with dev/test extras
python -m pytest test_autocti/                           # full test suite
python -m pytest test_autocti/extract/                   # one focused directory

In a sandboxed / restricted environment, point numba and matplotlib at writable caches:

NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autocti/

Related repos

  • Source siblings: PyAutoNerves, PyAutoArray, PyAutoFit (upstream).
  • autocti_workspace — runnable examples/tutorials (updated in epic Phase 4).
  • autocti_workspace_test — regression scripts + Euclid tvac/temporal heritage (rebuilt in epic Phase 5).
  • Science context: PyAutoMemory/wiki/cti/ (trap physics, arctic algorithm, Euclid VIS / HST ACS heritage).

Public API

The public surface is defined authoritatively in autocti/__init__.py — read it rather than trusting a hand-maintained table. Canonical import:

import autocti as ac

Key rules / footguns

  • Import direction: autoarray / autofit / autonerves only — never autogalaxy or autolens.
  • Unit tests are numpy-only; there is no JAX in this library (arctic is C++).
  • Slicing an autoarray Mask2D returns a plain ndarray — rebuild a Mask2D with the parent's pixel_scales before constructing an Array2D from it (see autocti/extract/two_d/abstract.py).
  • Fits I/O goes through autonerves.fitsable (ndarray_via_fits_from, output_to_fits, hdu_list_for_output_from) — instance .output_to_fits methods no longer exist on autoarray structures.
  • All files use Unix line endings (LF, \n) — never \r\n.

Working on issues

  1. Read the issue description and any linked plan.
  2. Identify affected files and make the change.
  3. Run the full suite: python -m pytest test_autocti/.
  4. If you changed public API, say so explicitly — autocti_workspace may need updates.
  5. Ensure all tests pass before opening a PR.

Never rewrite history

Never rewrite pushed history on any repo with a remote — no git init over a tracked repo, no force-push to main, no fresh-start "Initial commit", no filter-repo / filter-branch / rebase -i on pushed branches. To get a clean tree: git fetch origin && git reset --hard origin/main && git clean -fd.

Sessions end at their deliverable

A session ends when it reports its deliverable — never arm anything that outlives the turn to wait for CI, a review or a merge: no send_later, no subscribe_pr_activity, no CronCreate, no ScheduleWakeup, no /loop, no RemoteTrigger create/update/run. Judge once, report, stop; the human re-runs /prm (or the batch review) when it is green. Measured: five batch members armed hourly check-ins on 2026-08-31, and a mobile /prm re-armed a 60-minute send_later hourly all night on 2026-09-03 with no task active, draining usage.

Where to file

Questions, help with code or an analysis, ideas, bug reports and results from a user or collaborator — or an agent acting for one — go to https://github.com/orgs/PyAutoLabs/discussions in the matching category (Help & Questions, Ideas & Proposals, Bugs & Errors, Show and tell; Announcements is maintainers-only), never to this repo's Issues. An agent never runs gh issue create for such a report: it drafts the title, category and body and hands them to the human (sessions cannot create Discussions). Only the development flow — Mind prompt → /start_dev → /create_issue → one issue per task → PR — opens issues here. Why: PyAutoMind/policy/community_surface.md.

Shared standards

Before changing a shared interface, consult the applicable organism standard on demand, identify affected consumers, and validate their adoption. Change generated guidance at its canonical source and regenerate.