Add transform base class and example notebooks. Finalise docs

.github/workflows/testing.yml

@@ -39,18 +39,17 @@ jobs:
         conda config --set always_yes yes
         conda install mamba
         mamba install stackvana galsim pytest black fitsio \
-          matplotlib astropy
+          matplotlib astropy 'pybind11>=3,<4'
 
-        python -m pip install --upgrade pip
-        pip install -U setuptools
+        python -m pip install --upgrade pip setuptools wheel
 
-        pip install . --user
+        python -m pip install .
 
 
     - name: Lint with black
       shell: bash -l {0}
       run: |
-        black src/batsim
+        black --check src tests benchmarks setup.py docs/conf.py
 
     - name: Test with pytest
       shell: bash -l {0}

.gitignore

@@ -137,6 +137,7 @@ dask-worker-space/
 
 # tmp directory
 tmp/
+.nfs*
 
 # Mac OS
 .DS_Store
@@ -145,3 +146,9 @@ tmp/
 _results/
 _html/
 .hypothesis
+
+# Dev files
+*.fits
+notebooks/dev/
+notebooks/ia-analysis/
+notebooks/validation/

README.md

@@ -1,71 +1,113 @@
 # BATSim
 
-BATSim is designed to enable the application of non-affine shear
-transformations to GalSim images. It works by trasnforming the stamp pixel
-grid, distorting the location of the pixel centers. When a GalSim image is
-sampled onto this distorted grid, the resulting image will be sheared due to
-the transformation of the pixel grid.
+BATSim renders GalSim surface-brightness profiles on coordinate grids that can
+be transformed before sampling. This makes it possible to apply non-affine shear
+fields, such as intrinsic alignment and flexion, while keeping the rendering
+pipeline close to GalSim's image conventions.
+
+The current renderer samples profiles on a supersampled grid, optionally applies
+sub-pixel block integration, and performs PSF and pixel convolution in Fourier
+space. The default render path uses:
+
+- `psf_mode="kvalue"` for analytic PSF Fourier sampling through BATSim's C++ layer
+- `force_input_flux=True` to preserve the input galaxy flux after convolution
+- `use_true_center=True` to match GalSim's true-image-center convention
+- `integration_order=2` for Gauss-Legendre block integration
+- `compensate_integration="quadrature"` to remove the matching Gauss-Legendre
+  transfer function; pass `"exact_sinc"` for ideal top-hat compensation or
+  `None` to disable compensation
+- `backend="np"` by default, with optional CuPy support for FFT-heavy steps
+
+## Quickstart
+
+```python
+import galsim
+import batsim
+
+galaxy = galsim.Sersic(n=1.0, half_light_radius=0.7, flux=1.0)
+psf = galsim.Gaussian(fwhm=0.7)
+transform = batsim.IaTransform(scale=0.2, hlr=0.7, A=0.02)
+
+image = batsim.simulate_galaxy(
+    galaxy,
+    scale=0.2,
+    ngrid=64,
+    transform_obj=transform,
+    psf_obj=psf,
+)
+```
+
+`simulate_galaxy` returns a NumPy array. NumPy is used by default; pass
+`backend="cp"` to request CuPy for FFT-heavy steps.
+
+## Public API
 
-Non-affine transforms can simualate complex shear effects such as intrinsic
-alignment, flexion, and optical field distrotion maps. Custom transform
-functions can also be passed to Stamp objects.
+The stable top-level API is:
 
-## Building and installing BATSim from source (Conda + GalSim C++)
+- `batsim.simulate_galaxy`
+- `batsim.clear_backend_memory`
+- `batsim.Stamp`
+- `batsim.Transform` base class for custom coordinate transforms
+- `batsim.LensTransform` and `batsim.AffineLensingTransform`
+- `batsim.IaTransform` and `batsim.IATransform`
+- `batsim.FlexionTransform`
+- `batsim.experimental` for non-stable helpers such as SIP WCS parsing
 
-The package is not currently available on PyPI and only installable on Linux while in early development. We suggest using conda/mamba to build the package and install its dependencies. This is because the primary dependency, Galsim, does not ship a pre-built C++ library via pip.
+`batsim.pltutil` remains available for legacy plotting utilities used by older
+examples and validation notebooks.
 
-The below instructions will work with pure conda, but we recommend using mamba to make the installation of dependencies much quicker.
+## Building and Installing BATSim from Source
 
-First, make sure to clone and switch to the repository root:
+BATSim currently expects GalSim's C++ shared library to be available at build
+time. The recommended route is to use conda or mamba with dependencies from
+conda-forge.
+
+First, clone the repository and switch to the repository root:
 
 ```bash
 git clone https://github.com/CMacM/BATSim.git
 cd BATSim
 ```
 
-## Regular Install (not editable)
+### Regular Install
+
+Create and activate a build environment:
 
-### 1. Create build environment and activate
 ```bash
 mamba create -n batsim -c conda-forge -c defaults python=3.10 conda-build boa
 mamba activate batsim
 ```
 
-### 2. Build the package
-From the repository root:
+Build the package:
+
 ```bash
-# mambabuild is sometimes only recognised as a conda command
 conda mambabuild --override-channels -c conda-forge -c defaults conda/recipe
 ```
 
-This will:
-- Create an isolated environment to build and run batsim
-- Install all required dependencies
-- Compile the BATSim C++ extension and link it to Galsim's C++ API
-- Produce a conda package in:
+This creates an isolated build environment, installs dependencies, compiles the
+BATSim C++ extension, links it to GalSim's C++ API, and produces a conda package
+under:
+
 ```bash
 $CONDA_PREFIX/conda-bld/linux-64/
 ```
 
-### 3. Install the built package
-Install the locally built package into the new environment:
+Install the built package:
+
 ```bash
 mamba install -c local batsim
 ```
 
-If this fails, install directly from the build artifact:
+If needed, install directly from the build artifact:
+
 ```bash
 mamba install $CONDA_PREFIX/conda-bld/linux-64/batsim-*.tar.bz2
 ```
 
-## Development Installation (Editable)
-
-For development you can install BATSim in editable mode so that Python changes
-take effect immediately without reinstalling.
+### Development Install
 
-### 1. Create a development environment and activate
-
-Note: You may encounter issues if some of these packages are already installed locally and have different builds. To fix, remove them and ensure they are installed through conda-forge.
+For development, install BATSim in editable mode so Python changes take effect
+without reinstalling:
 
 ```bash
 mamba create -n batsim-dev -c conda-forge -c defaults \
@@ -78,26 +120,44 @@ mamba create -n batsim-dev -c conda-forge -c defaults \
     astropy \
     matplotlib
 mamba activate batsim-dev
+pip install -e .
 ```
 
-### 2. Install BATSim in editable mode
+Verify the installation:
 
 ```bash
-pip install -e .
+python -c "import batsim; import batsim._gsinterface; print('BATSim installed successfully')"
+```
+
+## Running Benchmarks
+
+BATSim uses ASV for performance benchmarks. Install the optional benchmark extra
+into a working BATSim development environment:
+
+```bash
+pip install -e ".[benchmark]"
 ```
 
-After following either of the above installation routes, with the conda environment active, verify the installation:
+Then run discovery and a quick smoke benchmark:
 
 ```bash
-python -c "import batsim; import batsim._gsinterface; print('BATSim installed successfully')"
+cd benchmarks
+asv check
+asv run --quick --show-stderr
 ```
 
-## Pip only installation
+The default benchmark suite uses deterministic analytic GalSim profiles and
+CPU-backed NumPy renders. Optional CuPy benchmarks skip automatically when a
+working CUDA runtime is not available.
 
-We currently do not provide a pip only installation route as Galsim requires the shared C++ library to be built and linked manually when installed via pip. If you wish to build via pip only, you will need to install all dependencies and build and link the Galsim C++ headers. You can find details on how to do this [here][https://galsim-developers.github.io/GalSim/_build/html/install_pip.html]. You may then need to update your LD\_LIBRARY\_PATH, LIBRARY\_PATH, and CPLUS\_INCLUDE\_PATH to point to build and include folders for the GalSim C++ shared library.
+## Pip-Only Installation
 
-We plan to add a pure pip installation route in future.
+A pure pip installation route is not currently provided because BATSim links
+against GalSim's shared C++ library. If you build GalSim's C++ library manually,
+set `GALSIM_LIB_DIR` and `GALSIM_INCLUDE_DIR` before installing BATSim. GalSim's
+pip build notes are available in the
+[GalSim documentation](https://galsim-developers.github.io/GalSim/_build/html/install_pip.html).
 
 ![BATSim Logo](./image/batsim_logo.png)
 
-(repo icon created using images by Frepik and brgfx on Freepik)
+Repository icon created using images by Frepik and brgfx on Freepik.

benchmarks/asv.conf.json

@@ -5,28 +5,14 @@
     "branches": [
         "HEAD"
     ],
-    "build_command": [
-        "python -m build --wheel -o {build_cache_dir} {build_dir}"
-    ],
     "dvcs": "git",
-    "environment_type": "virtualenv",
-    "show_commit_url": "Change this value according to the instructions on RTD",
+    "environment_type": "existing",
     "pythons": [
         "3.10"
     ],
-    "matrix": {
-        "Cython": [],
-        "build": [],
-        "packaging": []
-    },
     "benchmark_dir": ".",
     "env_dir": "env",
     "results_dir": "_results",
     "html_dir": "_html",
-    "build_cache_size": 8,
-    "benchmarks": {
-            "name": "time_shear_speed",
-            "params": [],
-            "number": 1
-    }
+    "build_cache_size": 8
 }