Home

spotgp: Gaussian Process kernels for stellar starspot variability implemented in JAX.

Installation

From PyPI

pip install spotgp

With JAX acceleration (recommended):

pip install "spotgp[jax]"

From source

git clone https://github.com/jbirky/spotgp.git
cd spotgp
pip install -e ".[jax]"

Alternatively, clone the repo and add it to your Python path:

git clone https://github.com/jbirky/spotgp.git
echo 'export PYTHONPATH="$PYTHONPATH:/path/to/spotgp"' >> ~/.bashrc
source ~/.bashrc

Development

This project is build and maintained by Jess Birky–keep an eye out for the paper (coming soon). If you are interested in contributing, feel free to reach out or make a pull request!

Documentation Contents

Basics

• Home
• Quickstart
  • 1. Define a spot evolution model
  • 2. Simulate a lightcurve
  • 3. Build the analytic kernel
  • 4. Fit the GP to data
  • 5. Inspect the fit
  • Next steps
• Time Domain
  • 1. Envelope Model \(\Gamma(t)\): spot growth and decay
  • 2. Visibility Function \(\Pi(t)\): rotational modulation
  • 3. Putting the Envelope and Visibility Components Together
• Fourier Domain
  • 1. Envelope Spectrum \(|\hat{\Gamma}(\omega)|\): spot lifetime sets the peak width
  • 2. Rotation Harmonics \(c_n^2\): inclination shapes the harmonic amplitudes
  • 3. Full Analytic PSD: combining envelope spectrum and rotation harmonics
• Code Overview
  • Module architecture
  • Module descriptions
  • Data flow: fitting a lightcurve
  • Extending the library
• Lightcurve Animations
  • Build a SpotEvolutionModel
  • Simulate a lightcurve
  • Create an animation of the star rotation and lightcurve
• Symbolic Equations with Sympy
  • 1. Envelope functions
  • 2. Visibility function
  • 3. Latitude distribution
  • 4. Parameter distributions
  • 5. Full model
  • Summary
• Analytic vs Numerical Kernel
  • 1. Define the spot model
  • 2. Compute both kernels
  • 3. Compare: autocorrelation functions
  • 4. Compare: power spectral density
  • 5. Speed comparison
  • 6. Convergence with number of simulations
  • 7. Effect of differential rotation
  • Summary
• Kernel JAX JIT Compilation
  • 1. Inspect the envelope
  • 2. Build a SpotEvolutionModel
  • 3. Simulate a stellar lightcurve
  • 4. Warm up JAX with build_jax()
• GP Solver
  • 1. Model setup and lightcurve simulation
  • 2. Warm up JAX with build_jax()
  • 3. GP hyperparameter fit — MAP solution
  • 4. Multi-start MAP (optional)
• Data Preprocessing
  • 1. Simulated data
  • 2. Kepler data with lightkurve
  • API summary

Advanced

• Custom Envelope Functions
  • 1. Analytic equations for the Gaussian envelope
  • 2. Minimal implementation — Gamma(t) only
  • 3. Add analytic Gamma_hat(omega)
  • 4. Add analytic R_Gamma(tlag)
  • 5. Build a SpotEvolutionModel with the Gaussian envelope
• Custom Visibility Functions
  • 1. The exact projected area
  • 2. Implementing a custom VisibilityFunction
  • 3. Visualize the projected area
  • 4. Compare Fourier coefficients \(|c_n|^2\)
  • 5. Divergence threshold: where does the approximation break down?
  • 6. Compare GP kernels
  • 7. Computation speed comparison
  • Summary
• Custom Latitude Distributions
  • 1. Default uniform distribution
  • 2. Equatorial band
  • 3. Gaussian-weighted distribution
  • 4. Polar band
  • 5. Kernel and lightcurve comparison
• Custom Spot Property Distributions
  • 1. Available distributions
  • 2. Distributed sigma_k — amplitude uncertainty
  • 3. Distributed lspot — spot lifetime variability
  • 4. Distributed tau_spot — emergence/decay timescale spread
  • 5. Combining multiple distributed parameters
  • 6. Custom distributions
  • Summary
• MCMC Sampling with BlackJAX
  • 1. Build the spot model and simulate a lightcurve
  • 2. Find the MAP estimate
  • 3. Run NUTS warmup and sampling
  • 4. Diagnostics and posterior summary
  • 5. Resume sampling in batches
  • 6. Visualize the posterior
• Nested Sampling with Dynesty
  • 1. Build the spot model and simulate a lightcurve
  • 2. Find the MAP estimate
  • 3. Run nested sampling with DynestySampler
  • 4. Diagnostics and posterior summary
  • 5. Dynamic nested sampling
  • 6. Visualize the posterior
• Cramér-Rao Bound
  • 1. Simulate a Synthetic Lightcurve
  • 2. Compute the Fisher Information Matrix
  • 3. Visualizing the CRB
  • 4. Dependence on Noise Level and Observation Baseline
  • Summary

API Reference

• API Reference (spotgp)
  • Lightcurve Model
  • Analytic Kernel
  • Numerical Kernel
  • GP Solver
  • Power Spectral Density
  • MCMC Sampler