gpimg 0.1.0__tar.gz

gpimg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francisco Förster
+
+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.

gpimg-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE README.md
+graft c
+graft tests
+prune c/build
+global-exclude *.o *.so *.a *.pyc
+include src/gpimg/*.c

gpimg-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: gpimg
+Version: 0.1.0
+Summary: Exact O(n) two-dimensional Gaussian-process fits and images of multi-band light curves
+Author-email: Francisco Förster <francisco.forster@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fforster/gpimg
+Project-URL: Documentation, https://gpimg.readthedocs.io
+Project-URL: Source, https://github.com/fforster/gpimg
+Keywords: gaussian process,light curves,state space,kalman filter,astronomy,LSST,transients
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: scipy>=1.9; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: furo>=2024.1; extra == "docs"
+Requires-Dist: numpydoc>=1.6; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: matplotlib>=3.7; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Dynamic: license-file
+
+# gpimg
+
+**Exact O(n) two-dimensional Gaussian processes for multi-band light curves.**
+
+gpimg fits a Gaussian process jointly in time and wavelength to a multi-band light curve and returns the posterior
+flux on any time × wavelength grid. The kernel is a Matérn-3/2 in time times a squared exponential in ln λ:
+
+    k((t,λ),(t',λ')) = A² (1 + √3|t−t'|/ℓt) exp(−√3|t−t'|/ℓt) · exp(−(ln λ − ln λ')² / 2ℓλ²)
+
+Because the time kernel is a linear stochastic differential equation and the kernel is separable, a light curve
+observed in up to six bands is *exactly* a small linear Gaussian state-space model. gpimg evaluates the likelihood,
+its analytic gradient, maximum-likelihood fits and posterior images with Kalman filters and smoothers in **O(n)**,
+with no approximation.
+
+- Exact: likelihoods agree with a dense Cholesky GP to ~1e-11 (relative).
+- Fast: one likelihood + gradient of an 18 668-point light curve in 4.7 ms on one core; a fit of a typical
+  deep-drilling LSST light curve (~660 points) in ~19 ms with five starts — 279× faster than PISCOLA's GP fit, and
+  1 100× faster for wide-fast-deep light curves (~64 points).
+- Compiled C core, no JIT and no warm-up; AVX2 + FMA code selected at run time; OpenMP batches.
+- Posteriors at any wavelength, smoothed or causal (real time), with an optional numerically stable
+  Rauch–Tung–Striebel smoother, and exact band–band covariances for colors.
+- Optional fitted jitter for scatter the quoted errors do not describe; off by default, and off costs nothing.
+- Python package and plain C library (Makefile, CMake, pkg-config).
+
+Documentation: the Sphinx sources under `docs/` (guide, Python API, C API, theory). A hosted build is not up yet.
+
+## Installation
+
+```console
+$ pip install gpimg
+```
+
+gpimg ships as a source distribution, so this compiles the C core for your machine: you need a C compiler (gcc or
+clang). OpenMP is optional — without it `gpimg.batch` runs serially and everything else is unaffected. An AVX2 +
+FMA copy is built alongside the portable one and chosen at import when the CPU supports it.
+
+From a source checkout, which also gets you the plain C library:
+
+```console
+$ pip install .                        # the Python package
+$ pytest                               # optional: pip install ".[test]" first
+$ make -C c && make -C c test          # the C library: build/libgpimg.so, build/libgpimg.a
+$ sudo make -C c install               # or: cmake -S c -B build && cmake --build build
+```
+
+## Python quick start
+
+```python
+import numpy as np
+import gpimg
+
+# t [days], band ('u','g','r','i','z','y' or 0..5; LSST by default), flux and flux_err in any flux unit
+gp = gpimg.GP(t, band, flux, flux_err)
+res = gp.fit()                                     # maximum likelihood, 5 starting points
+print(res.amplitude, res.length_time, res.length_wave, res.message)
+res = gp.fit(jitter=True)                          # + a white jitter for extra scatter; res.jitter
+
+img = gp.predict(np.linspace(-30, 120, 300),       # times [d]
+                 np.geomspace(3200, 10200, 200))   # wavelengths [Å]
+img.mean.shape, img.std.shape                      # (200, 300): wavelengths x times
+
+curves = gp.predict_bands(np.linspace(-30, 120, 300))     # {'u': (mean, std), ...}
+curves, covs = gp.predict_bands(t_grid, cov=True)         # + {('g','r'): cov, ...} for color errors
+live = gp.predict(t_grid, causal=True)                    # filtered: data up to each time only
+stable = gp.predict(t_grid, wave_grid, smoother="rts")    # numerically stable smoother
+```
+
+Many light curves from one long table (pandas, astropy, dict of arrays), fitted and imaged in parallel:
+
+```python
+lcs = gpimg.LightCurves.from_table(table, id="oid", t="t", band="band", flux="flux", flux_err="flux_err")
+res = gpimg.batch(lcs, np.linspace(-30, 120, 300), np.geomspace(3200, 10200, 200))
+res.mean.shape        # (n_objects, 200, 300), float32
+```
+
+Other surveys: `gpimg.GP(t, band, flux, err, wavelengths={"g": 4800.0, "r": 6400.0, "i": 7900.0})`.
+
+Runnable examples are in `examples/` (`quickstart.py`, `batch_table.py`, `causal_vs_smoothed.py`,
+`other_survey.py`).
+
+## C quick start
+
+```c
+#include "gpimg.h"
+
+double lnwave[6];                               /* ln of the band wavelengths */
+gp_fit_opts opts;
+gp_fit_default_opts(&opts);
+opts.nstart = 5;
+gp_fit_result res;
+gp_fit(n, t, band, y, err, lnwave, theta0, &opts, &res);                  /* res.theta = (ln A, ln lt, ln ll) */
+gp_image(n, t, band, y, err, 6, lnwave, res.theta, nt, tg, nl, lng, mean, var, GPIMG_SMOOTH(GPIMG_RTS));
+/* gp_image_cov(...) additionally fills cov[npair][nt] for pairs (pa[p], pb[p]) of grid wavelengths */
+```
+
+See `c/examples/example.c` and the C API reference in `docs/c_api.rst`.
+
+## Performance and accuracy
+
+Single core, Intel Core Ultra 7 255U; simulated LSST light curves (details in `docs/guide/performance.rst` and
+`docs/guide/accuracy.rst`).
+
+| likelihood + gradient | gpimg | dense GP (tinygp, warm) | smolgp, same model (warm) |
+|---|---|---|---|
+| 1 000 points | 0.20 ms | 165 ms | 12 ms |
+| 12 000 points | 2.8 ms | 242 s | 0.27 s |
+| 18 668 points | 4.7 ms | — | 0.41 s |
+
+| median per fit | DDF (~660 points) | WFD (~64 points) |
+|---|---|---|
+| gpimg, 5 starts | 18.7 ms | 1.7 ms |
+| PISCOLA as shipped | 4.95 s | 2.17 s |
+
+Against a dense double-precision GP with the same hyperparameters: likelihood ≤ 3.5e-11, gradient ≤ 8.4e-9 and
+posterior mean ≤ 1.1e-10 (relative). With `smoother="rts"` the posterior variance agrees with a 200-bit reference
+to 7e-10 at the grid points where the default smoother is worst (4.8e-3).
+
+## Citing
+
+A paper describing gpimg is in preparation (ApJ Letters). Until then please cite the software and the works in the
+references (`docs/references.rst`), in particular Hartikainen & Särkkä (2010) for
+the state-space formulation of temporal Gaussian processes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

gpimg-0.1.0/README.md

@@ -0,0 +1,126 @@
+# gpimg
+
+**Exact O(n) two-dimensional Gaussian processes for multi-band light curves.**
+
+gpimg fits a Gaussian process jointly in time and wavelength to a multi-band light curve and returns the posterior
+flux on any time × wavelength grid. The kernel is a Matérn-3/2 in time times a squared exponential in ln λ:
+
+    k((t,λ),(t',λ')) = A² (1 + √3|t−t'|/ℓt) exp(−√3|t−t'|/ℓt) · exp(−(ln λ − ln λ')² / 2ℓλ²)
+
+Because the time kernel is a linear stochastic differential equation and the kernel is separable, a light curve
+observed in up to six bands is *exactly* a small linear Gaussian state-space model. gpimg evaluates the likelihood,
+its analytic gradient, maximum-likelihood fits and posterior images with Kalman filters and smoothers in **O(n)**,
+with no approximation.
+
+- Exact: likelihoods agree with a dense Cholesky GP to ~1e-11 (relative).
+- Fast: one likelihood + gradient of an 18 668-point light curve in 4.7 ms on one core; a fit of a typical
+  deep-drilling LSST light curve (~660 points) in ~19 ms with five starts — 279× faster than PISCOLA's GP fit, and
+  1 100× faster for wide-fast-deep light curves (~64 points).
+- Compiled C core, no JIT and no warm-up; AVX2 + FMA code selected at run time; OpenMP batches.
+- Posteriors at any wavelength, smoothed or causal (real time), with an optional numerically stable
+  Rauch–Tung–Striebel smoother, and exact band–band covariances for colors.
+- Optional fitted jitter for scatter the quoted errors do not describe; off by default, and off costs nothing.
+- Python package and plain C library (Makefile, CMake, pkg-config).
+
+Documentation: the Sphinx sources under `docs/` (guide, Python API, C API, theory). A hosted build is not up yet.
+
+## Installation
+
+```console
+$ pip install gpimg
+```
+
+gpimg ships as a source distribution, so this compiles the C core for your machine: you need a C compiler (gcc or
+clang). OpenMP is optional — without it `gpimg.batch` runs serially and everything else is unaffected. An AVX2 +
+FMA copy is built alongside the portable one and chosen at import when the CPU supports it.
+
+From a source checkout, which also gets you the plain C library:
+
+```console
+$ pip install .                        # the Python package
+$ pytest                               # optional: pip install ".[test]" first
+$ make -C c && make -C c test          # the C library: build/libgpimg.so, build/libgpimg.a
+$ sudo make -C c install               # or: cmake -S c -B build && cmake --build build
+```
+
+## Python quick start
+
+```python
+import numpy as np
+import gpimg
+
+# t [days], band ('u','g','r','i','z','y' or 0..5; LSST by default), flux and flux_err in any flux unit
+gp = gpimg.GP(t, band, flux, flux_err)
+res = gp.fit()                                     # maximum likelihood, 5 starting points
+print(res.amplitude, res.length_time, res.length_wave, res.message)
+res = gp.fit(jitter=True)                          # + a white jitter for extra scatter; res.jitter
+
+img = gp.predict(np.linspace(-30, 120, 300),       # times [d]
+                 np.geomspace(3200, 10200, 200))   # wavelengths [Å]
+img.mean.shape, img.std.shape                      # (200, 300): wavelengths x times
+
+curves = gp.predict_bands(np.linspace(-30, 120, 300))     # {'u': (mean, std), ...}
+curves, covs = gp.predict_bands(t_grid, cov=True)         # + {('g','r'): cov, ...} for color errors
+live = gp.predict(t_grid, causal=True)                    # filtered: data up to each time only
+stable = gp.predict(t_grid, wave_grid, smoother="rts")    # numerically stable smoother
+```
+
+Many light curves from one long table (pandas, astropy, dict of arrays), fitted and imaged in parallel:
+
+```python
+lcs = gpimg.LightCurves.from_table(table, id="oid", t="t", band="band", flux="flux", flux_err="flux_err")
+res = gpimg.batch(lcs, np.linspace(-30, 120, 300), np.geomspace(3200, 10200, 200))
+res.mean.shape        # (n_objects, 200, 300), float32
+```
+
+Other surveys: `gpimg.GP(t, band, flux, err, wavelengths={"g": 4800.0, "r": 6400.0, "i": 7900.0})`.
+
+Runnable examples are in `examples/` (`quickstart.py`, `batch_table.py`, `causal_vs_smoothed.py`,
+`other_survey.py`).
+
+## C quick start
+
+```c
+#include "gpimg.h"
+
+double lnwave[6];                               /* ln of the band wavelengths */
+gp_fit_opts opts;
+gp_fit_default_opts(&opts);
+opts.nstart = 5;
+gp_fit_result res;
+gp_fit(n, t, band, y, err, lnwave, theta0, &opts, &res);                  /* res.theta = (ln A, ln lt, ln ll) */
+gp_image(n, t, band, y, err, 6, lnwave, res.theta, nt, tg, nl, lng, mean, var, GPIMG_SMOOTH(GPIMG_RTS));
+/* gp_image_cov(...) additionally fills cov[npair][nt] for pairs (pa[p], pb[p]) of grid wavelengths */
+```
+
+See `c/examples/example.c` and the C API reference in `docs/c_api.rst`.
+
+## Performance and accuracy
+
+Single core, Intel Core Ultra 7 255U; simulated LSST light curves (details in `docs/guide/performance.rst` and
+`docs/guide/accuracy.rst`).
+
+| likelihood + gradient | gpimg | dense GP (tinygp, warm) | smolgp, same model (warm) |
+|---|---|---|---|
+| 1 000 points | 0.20 ms | 165 ms | 12 ms |
+| 12 000 points | 2.8 ms | 242 s | 0.27 s |
+| 18 668 points | 4.7 ms | — | 0.41 s |
+
+| median per fit | DDF (~660 points) | WFD (~64 points) |
+|---|---|---|
+| gpimg, 5 starts | 18.7 ms | 1.7 ms |
+| PISCOLA as shipped | 4.95 s | 2.17 s |
+
+Against a dense double-precision GP with the same hyperparameters: likelihood ≤ 3.5e-11, gradient ≤ 8.4e-9 and
+posterior mean ≤ 1.1e-10 (relative). With `smoother="rts"` the posterior variance agrees with a 200-bit reference
+to 7e-10 at the grid points where the default smoother is worst (4.8e-3).
+
+## Citing
+
+A paper describing gpimg is in preparation (ApJ Letters). Until then please cite the software and the works in the
+references (`docs/references.rst`), in particular Hartikainen & Särkkä (2010) for
+the state-space formulation of temporal Gaussian processes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

gpimg-0.1.0/c/CMakeLists.txt

@@ -0,0 +1,55 @@
+cmake_minimum_required(VERSION 3.16)
+project(gpimg VERSION 0.1.0 LANGUAGES C)
+
+# gpimg C library. Usage:
+#   cmake -S c -B build -DCMAKE_BUILD_TYPE=Release [-DGPIMG_NATIVE=ON] && cmake --build build && ctest --test-dir build
+# In another CMake project: add_subdirectory(gpimg/c) or find_package(gpimg) after installation, then
+#   target_link_libraries(myapp PRIVATE gpimg::gpimg)
+
+option(GPIMG_OPENMP "Parallel gp_batch with OpenMP" ON)
+option(GPIMG_NATIVE "Optimise for the build machine (-march=native)" OFF)
+option(BUILD_SHARED_LIBS "Build a shared library" ON)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_EXTENSIONS ON)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+add_library(gpimg src/gpimg.c)
+add_library(gpimg::gpimg ALIAS gpimg)
+target_include_directories(gpimg PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+                                        $<INSTALL_INTERFACE:include>)
+set_target_properties(gpimg PROPERTIES VERSION ${PROJECT_VERSION} SOVERSION 0 POSITION_INDEPENDENT_CODE ON)
+if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+  # IEEE semantics are kept (no -ffast-math); FMA contraction is allowed
+  target_compile_options(gpimg PRIVATE -O3 -fno-math-errno -ffp-contract=fast -Wall -Wextra)
+  if(GPIMG_NATIVE)
+    target_compile_options(gpimg PRIVATE -march=native)
+  endif()
+endif()
+find_library(MATH_LIBRARY m)
+if(MATH_LIBRARY)
+  target_link_libraries(gpimg PUBLIC ${MATH_LIBRARY})
+endif()
+if(GPIMG_OPENMP)
+  find_package(OpenMP COMPONENTS C)
+  if(OpenMP_C_FOUND)
+    target_link_libraries(gpimg PUBLIC OpenMP::OpenMP_C)
+  endif()
+endif()
+
+add_executable(gpimg_example examples/example.c)
+target_link_libraries(gpimg_example PRIVATE gpimg)
+
+enable_testing()
+add_executable(test_gpimg tests/test_gpimg.c)
+target_link_libraries(test_gpimg PRIVATE gpimg)
+add_test(NAME test_gpimg COMMAND test_gpimg)
+
+include(GNUInstallDirs)
+install(TARGETS gpimg EXPORT gpimgTargets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(FILES include/gpimg.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(EXPORT gpimgTargets NAMESPACE gpimg:: FILE gpimgConfig.cmake
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/gpimg)

gpimg-0.1.0/c/Makefile

@@ -0,0 +1,81 @@
+# gpimg C library: exact O(n) 2D Gaussian processes for multi-band light curves.
+#
+#   make                 shared + static library in build/ (libgpimg.so / .dylib, libgpimg.a)
+#   make example         build/example (fit + image of a synthetic light curve)
+#   make test            build/test_gpimg, run it (likelihood vs dense Cholesky, gradients, smoothers)
+#   make install         PREFIX=/usr/local by default: lib/, include/gpimg.h, lib/pkgconfig/gpimg.pc
+#
+# Variables: CC (default cc), ARCH (e.g. ARCH=-march=native for the fastest build on this machine),
+# OPENMP=0 to build without OpenMP (gp_batch then runs serially), PREFIX, DESTDIR.
+CC      ?= cc
+ARCH    ?=
+OPENMP  ?= 1
+PREFIX  ?= /usr/local
+VERSION := 0.1.0
+
+UNAME := $(shell uname -s)
+ifeq ($(UNAME),Darwin)
+  SHLIB := libgpimg.dylib
+  SHFLAGS := -dynamiclib -install_name $(PREFIX)/lib/$(SHLIB)
+else
+  SHLIB := libgpimg.so
+  SHFLAGS := -shared -Wl,-soname,libgpimg.so.0
+endif
+
+# IEEE semantics are kept (no -ffast-math); FMA contraction is allowed.
+CFLAGS_BASE := -O3 $(ARCH) -fno-math-errno -ffp-contract=fast -fPIC -std=gnu11 -Wall -Wextra -Iinclude
+ifeq ($(OPENMP),1)
+  OMPFLAGS := -fopenmp
+endif
+CFLAGS_ALL := $(CFLAGS_BASE) $(OMPFLAGS) $(CFLAGS)
+LDLIBS_ALL := $(OMPFLAGS) -lm
+
+B := build
+
+all: $(B)/$(SHLIB) $(B)/libgpimg.a
+
+$(B):
+	mkdir -p $(B)
+
+$(B)/gpimg.o: src/gpimg.c include/gpimg.h | $(B)
+	$(CC) $(CFLAGS_ALL) -c $< -o $@
+
+$(B)/$(SHLIB): $(B)/gpimg.o
+	$(CC) $(SHFLAGS) $< -o $@ $(LDLIBS_ALL) $(LDFLAGS)
+
+$(B)/libgpimg.a: $(B)/gpimg.o
+	$(AR) rcs $@ $<
+
+$(B)/example: examples/example.c $(B)/libgpimg.a
+	$(CC) $(CFLAGS_ALL) $< $(B)/libgpimg.a -o $@ $(LDLIBS_ALL) $(LDFLAGS)
+
+$(B)/test_gpimg: tests/test_gpimg.c $(B)/libgpimg.a
+	$(CC) $(CFLAGS_ALL) $< $(B)/libgpimg.a -o $@ $(LDLIBS_ALL) $(LDFLAGS)
+
+example: $(B)/example
+	./$(B)/example
+
+test: $(B)/test_gpimg
+	./$(B)/test_gpimg
+
+$(B)/gpimg.pc: | $(B)
+	printf 'prefix=$(PREFIX)\nlibdir=$${prefix}/lib\nincludedir=$${prefix}/include\n\nName: gpimg\nDescription: Exact O(n) 2D Gaussian processes for multi-band light curves\nVersion: $(VERSION)\nLibs: -L$${libdir} -lgpimg\nLibs.private: $(OMPFLAGS) -lm\nCflags: -I$${includedir}\n' > $@
+
+install: all $(B)/gpimg.pc
+	install -d $(DESTDIR)$(PREFIX)/lib $(DESTDIR)$(PREFIX)/include $(DESTDIR)$(PREFIX)/lib/pkgconfig
+	install -m 644 include/gpimg.h $(DESTDIR)$(PREFIX)/include/
+	install -m 755 $(B)/$(SHLIB) $(DESTDIR)$(PREFIX)/lib/
+	install -m 644 $(B)/libgpimg.a $(DESTDIR)$(PREFIX)/lib/
+	install -m 644 $(B)/gpimg.pc $(DESTDIR)$(PREFIX)/lib/pkgconfig/
+ifneq ($(UNAME),Darwin)
+	ln -sf $(SHLIB) $(DESTDIR)$(PREFIX)/lib/libgpimg.so.0
+endif
+
+uninstall:
+	rm -f $(DESTDIR)$(PREFIX)/include/gpimg.h $(DESTDIR)$(PREFIX)/lib/$(SHLIB) $(DESTDIR)$(PREFIX)/lib/libgpimg.so.0 \
+	      $(DESTDIR)$(PREFIX)/lib/libgpimg.a $(DESTDIR)$(PREFIX)/lib/pkgconfig/gpimg.pc
+
+clean:
+	rm -rf $(B)
+
+.PHONY: all example test install uninstall clean

gpimg-0.1.0/c/examples/example.c

@@ -0,0 +1,68 @@
+/* example.c -- fit and image a synthetic six-band light curve with the gpimg C library.
+ *
+ *   make -C c example            (or: cc -O2 example.c -Iinclude -Lbuild -lgpimg -lm -fopenmp)
+ *
+ * Times in days, wavelengths in Angstrom (passed as natural logs), fluxes in any unit.
+ */
+#include <math.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "gpimg.h"
+
+int main(void)
+{
+    /* LSST ugrizy effective wavelengths -> ln(lambda) */
+    const double wave[6] = {3671.0, 4827.0, 6223.0, 7546.0, 8691.0, 9712.0};
+    double lnwave[6];
+    for (int b = 0; b < 6; b++) lnwave[b] = log(wave[b]);
+
+    /* a synthetic transient: rise and decline, redder bands peak later, observed every ~3 days in one band */
+    enum { N = 120 };
+    double t[N], y[N], err[N];
+    int32_t band[N];
+    srand(1);
+    for (int i = 0; i < N; i++) {
+        t[i] = -20.0 + 1.0 * i + 0.5 * rand() / (double)RAND_MAX;
+        band[i] = i % 6;
+        const double tp = 1.0 * band[i], x = t[i] - tp;   /* peak time: one day later per band */
+        const double f = 1000.0 * exp(-x / 25.0) / (1.0 + exp(-x / 3.0));
+        err[i] = 20.0;
+        y[i] = f + err[i] * (2.0 * rand() / (double)RAND_MAX - 1.0);
+    }
+
+    /* maximum-likelihood fit: theta = (ln A, ln l_t, ln l_lambda) */
+    gp_fit_opts opts;
+    gp_fit_default_opts(&opts);
+    opts.nstart = 5;
+    const double theta0[3] = {log(1000.0), log(20.0), log(0.8)};
+    gp_fit_result res;
+    gp_fit(N, t, band, y, err, lnwave, theta0, &opts, &res);
+    printf("fit: A = %.1f, l_t = %.2f d, l_lambda = %.3f (ln lambda); -ln L = %.3f; %d iterations, status %d\n",
+           exp(res.theta[0]), exp(res.theta[1]), exp(res.theta[2]), res.nll, res.nit, res.status);
+
+    /* likelihood and its analytic gradient at the optimum */
+    double grad[3];
+    const double nll = gp_nll_grad(N, t, band, y, err, lnwave, 3, res.theta, grad);
+    printf("-ln L = %.6f, gradient = (%.2e, %.2e, %.2e)\n", nll, grad[0], grad[1], grad[2]);
+
+    /* posterior image on 100 times x 50 wavelengths, smoothed (MBF) and with the stable RTS smoother */
+    enum { NT = 100, NL = 50 };
+    double tg[NT], lng[NL];
+    for (int g = 0; g < NT; g++) tg[g] = -30.0 + 130.0 * g / (NT - 1);
+    for (int l = 0; l < NL; l++) lng[l] = log(3200.0) + (log(10200.0) - log(3200.0)) * l / (NL - 1);
+    double *mean = malloc(sizeof(double) * NL * NT), *var = malloc(sizeof(double) * NL * NT);
+    const int rank = gp_image(N, t, band, y, err, 6, lnwave, 3, res.theta, NT, tg, NL, lng, mean, var,
+                              GPIMG_SMOOTH(GPIMG_RTS));
+    const int l = NL / 2, g = NT / 2;
+    printf("image (rank %d): at t = %.1f d, lambda = %.0f A: flux = %.1f +- %.1f\n", rank, tg[g], exp(lng[l]),
+           mean[l * NT + g], sqrt(var[l * NT + g]));
+
+    /* the same column as known in real time: filtered (causal) posterior */
+    gp_image(N, t, band, y, err, 6, lnwave, 3, res.theta, NT, tg, NL, lng, mean, var, GPIMG_CAUSAL);
+    printf("causal image at the same point: flux = %.1f +- %.1f\n", mean[l * NT + g], sqrt(var[l * NT + g]));
+    free(mean);
+    free(var);
+    return 0;
+}

gpimg-0.1.0/c/include/gpimg.h

@@ -0,0 +1,113 @@
+/* gpimg: exact O(n) two-dimensional Gaussian-process fits and images for multi-band light curves.
+ *
+ * Kernel
+ *   k((t,x),(t',x')) = A^2 (1 + sqrt3|dt|/lt) exp(-sqrt3|dt|/lt) exp(-(x-x')^2 / (2 ll^2)),  x = ln(lambda)
+ * zero mean, measurement variances err^2 on the diagonal. Hyperparameters theta = (ln A, ln lt, ln ll).
+ *
+ * Optional jitter. Every function taking theta also takes ntheta: 3 for the kernel above, or 4 to add a white
+ * jitter variance j^2 = exp(2 theta[3]) to every measurement variance -- extra scatter beyond the quoted errors,
+ * fitted like any other hyperparameter (analytic gradient, bounds opts->lo[3]/hi[3], opts->ntheta = 4). It is
+ * optional in the strict sense: ntheta = 3 never reads theta[3] and costs nothing -- the likelihood, its gradient
+ * and the whole image path are bit-identical to the three-parameter library (gp_fit lands on the same optimum to
+ * ~1e-8 in theta, far inside its own pgtol, since a BFGS iterate path is not bit-reproducible across builds).
+ * j is in the flux unit of y, so scale its bounds to your data.
+ *
+ * The Matern-3/2 time kernel is a 2-state linear SDE and the kernel is separable, so the GP observed in B <= 6
+ * bands is an exact 2B-state linear Gaussian state-space model: the Kalman filter gives the exact likelihood, a
+ * smoother the exact posterior, and any wavelength follows exactly from the band processes. No approximation is made.
+ *
+ * Inputs need not be time-sorted. band[i] in 0..nband_tot-1 indexes lnwave[]. Times in any unit consistent with
+ * lt (days in the Python package). All functions are re-entrant (no global state) and thread-safe.
+ */
+#ifndef GPIMG_H
+#define GPIMG_H
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define GPIMG_VERSION "0.1.0"
+#define GPIMG_MAXB 6
+#define GPIMG_MAXTHETA 4   /* (ln A, ln lt, ln ll) and the optional ln jitter */
+#define GPIMG_NINFO 6   /* per-object info: nll, nit, nfev, status, t_fit [s], t_image [s] */
+
+/* image mode: GPIMG_CAUSAL (filtered posteriors) or a smoother, e.g. GPIMG_SMOOTH(GPIMG_RTS) */
+#define GPIMG_CAUSAL 1
+#define GPIMG_MBF 0         /* modified Bryson-Frazier: inversion-free, fastest (default) */
+#define GPIMG_RTS 1         /* Rauch-Tung-Striebel, Joseph form: numerically stable */
+#define GPIMG_RTS_PLAIN 2   /* Rauch-Tung-Striebel, textbook form */
+#define GPIMG_SMOOTH(s) ((s) << 1)
+#define GPIMG_SMOOTHER(mode) (((mode) >> 1) & 3)
+
+/* negative log marginal likelihood (incl. 0.5 n ln 2pi) and, if grad != NULL, its gradient wrt theta */
+double gp_nll_grad(int n, const double *t, const int32_t *band, const double *y, const double *err,
+                   const double *lnwave, int ntheta, const double *theta, double *grad);
+
+/* testing: gradient by reverse mode (adjoint) and by forward mode; gnoise = sum_i err_i^2 dL/d(err_i^2) */
+/* grad_fwd[3] (the jitter) is returned as NaN: the forward tangents cover the three kernel parameters. */
+double gp_nll_grad_check(int n, const double *t, const int32_t *band, const double *y, const double *err,
+                         const double *lnwave, int ntheta, const double *theta, double *grad_adj,
+                         double *grad_fwd, double *gnoise);
+
+/* fit options / result */
+typedef struct {
+    double lo[GPIMG_MAXTHETA], hi[GPIMG_MAXTHETA];   /* bounds on theta; [3] read only when ntheta = 4 */
+    double pgtol;          /* stop when max |projected gradient| <= pgtol */
+    double ftol;           /* stop when (f_old - f) <= ftol * max(|f|, 1) */
+    int maxiter;
+    int nstart;            /* 1: start at theta0 only. k > 1: also the first k-1 points of a fixed design around
+                              theta0 (GPIMG_NDESIGN max); keep the lowest -lnL (multimodal likelihoods) */
+    int ntheta;            /* 3 (default) or 4: fit the jitter too. theta0 and res.theta have this many entries */
+} gp_fit_opts;
+
+#define GPIMG_NDESIGN 18
+
+typedef struct {
+    double theta[GPIMG_MAXTHETA];   /* opts->ntheta entries are written */
+    double nll;
+    double pgnorm;
+    int nit, nfev, status;  /* status: 0 pgtol, 1 ftol, 2 maxiter, 3 line search failed */
+} gp_fit_result;
+
+void gp_fit_default_opts(gp_fit_opts *o);
+
+/* maximum-likelihood fit starting at theta0 (projected onto the bounds) */
+void gp_fit(int n, const double *t, const int32_t *band, const double *y, const double *err,
+            const double *lnwave, const double *theta0, const gp_fit_opts *opts, gp_fit_result *res);
+
+/* posterior mean and variance of the noise-free flux on the grid tg[nt] x lng[nl] (ln lambda); tg must be sorted
+ * ascending. Out arrays are row-major [nl][nt] (wavelength rows, time columns). nband_tot: bands in lnwave (<= 6).
+ * mode: see GPIMG_CAUSAL / GPIMG_SMOOTH above (0 = smoothed, MBF). Returns the latent rank used. */
+int gp_image(int n, const double *t, const int32_t *band, const double *y, const double *err,
+             int nband_tot, const double *lnwave, int ntheta, const double *theta,
+             int nt, const double *tg, int nl, const double *lng, double *mean, double *var, int mode);
+
+/* As gp_image, plus the same-time posterior covariance of pairs of grid wavelengths:
+ *   cov[p * nt + g] = cov(f(tg[g], lng[pa[p]]), f(tg[g], lng[pb[p]])),  p = 0..npair-1.
+ * pa/pb index lng[] and are NOT range-checked; pa[p] == pb[p] reproduces that wavelength's variance. cov is never
+ * clamped (a covariance may be negative). npair = 0 or cov = NULL behaves exactly like gp_image. Cost: O(npair nt)
+ * on top of the image, with no extra filter or smoother pass. */
+int gp_image_cov(int n, const double *t, const int32_t *band, const double *y, const double *err,
+                 int nband_tot, const double *lnwave, int ntheta, const double *theta,
+                 int nt, const double *tg, int nl, const double *lng, double *mean, double *var,
+                 int npair, const int32_t *pa, const int32_t *pb, double *cov, int mode);
+
+/* nll computed through the latent (image) model: cross-check of the two state-space formulations */
+double gp_nll_latent(int n, const double *t, const int32_t *band, const double *y, const double *err,
+                     int nband_tot, const double *lnwave, int ntheta, const double *theta);
+
+/* batch: objects o = 0..nobj-1 own rows off[o]..off[o+1]-1. Fits (if fit != 0, starting at theta0[o]) and
+ * makes images for every object with OpenMP. theta0/theta_out are [nobj][opts->ntheta].
+ * Outputs float32 mean/var [nobj][nl][nt], theta_out [nobj][ntheta],
+ * info [nobj][GPIMG_NINFO] = (nll, nit, nfev, status, t_fit, t_image). nthreads <= 0: OpenMP default. */
+void gp_batch(int nobj, const int64_t *off, const double *t, const int32_t *band, const double *y,
+              const double *err, int nband_tot, const double *lnwave, const double *theta0, int fit,
+              const gp_fit_opts *opts, int nt, const double *tg, int nl, const double *lng,
+              float *mean, float *var, double *theta_out, double *info, int mode, int nthreads);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif