# _scarlet2_ Documentation

_scarlet2_ is an open-source python library for modeling astronomical sources from multi-band, multi-epoch, and
multi-instrument data. It provides non-parametric and parametric models, can handle source overlap (aka blending), and
can integrate neural network priors. It's designed to be modular, flexible, and powerful.

_scarlet2_ is implemented in [jax](http://jax.readthedocs.io/), layered on top of
the [equinox](https://docs.kidger.site/equinox/)
library. It can be deployed to GPUs and TPUs and supports optimization and sampling approaches.

## Installation

For performance reasons, you should first install `jax` with the suitable `jaxlib` for your platform. After that

```
pip install scarlet2
```

should do. If you want the latest development version, use

```
pip install git+https://github.com/pmelchior/scarlet2.git
```

This will allow you to evaluate source models and compute likelihoods of observed data, so you can run your own
optimizer/sampler. If you want a fully fledged library out of the box, you need to install `optax`, `numpyro`, and
`h5py` as well.

## Usage

```{toctree}
:maxdepth: 2

0-quickstart
0-example
1-howto
3-validation
api
```

## Differences between _scarlet_ and _scarlet2_

[_scarlet_](https://pmelchior.github.io/scarlet/) was introduced by
[Melchior et al. (2018)](https://doi.org/10.1016/j.ascom.2018.07.001) to solve the deblending problem for the Rubin
Observatory. A stripped down version of it (developed by Fred Moolekamp) runs as part of the Rubin Observatory software
stack and is used for their data releases. We now call this version _scarlet1_.

_scarlet2_ follows very similar concepts. So, what's different?

### Model specification

_scarlet1_ is designed for a specific purpose: deblending for the Rubin Observatory. That has implications for the
quality and type of data it needs to work with. **_scarlet2_ is much more flexible to handle complex sources
configurations**, e.g. strong-lensing systems, supernova host galaxies, transient sources, etc.

This flexibility led us to carefully design a "language" to construct sources. It allows new source combinations and
is more explicit about the parameters and their initialization.

### Compute

Because some of the constraints in _scarlet1_ are expensive to evaluate, they are implemented in C++, which requires
the installation of a lot of additional code just to get it to run. **_scarlet2_ is implemented entirely in jax.**
A combination of `conda` and `pip` will get it installed. Unlike _scarlet1_, it will also run on GPUs and TPUs, and
performs just-in-time compilation of the model evaluation.

In addition, we can now interface with deep learning methods. In particular, we can employ neural networks as
data-driven priors, which helps break the degeneracies that arise when multiple components need to be
fit at the same time.

### Constraints and Priors

_scarlet1_ uses constrained optimization to help with fitting degeneracies, but that requires non-standard
(namely proximal) optimization because these constraints are not differentiable.
That can lead to problems with convergence, but, more importantly, it prevents the use of gradients on the 
constrained objective function. As a result, we could never calculate errors for _scarlet1_ models.
**_scarlet2_ uses only constraints that can be differentiated.**

_scarlet2_ also permit differentiable priors on all parameters,  so that one can express Bayesian posterior as
the objective for sampling, optimization, and error estimation.

## Ideas, Questions or Problems?

If you have any of those, head over to our [github repo](https://github.com/pmelchior/scarlet2/) and create an issue.
For other ways to contribute, check out
our [contributing guide](https://github.com/pmelchior/scarlet2/blob/main/CONTRIBUTING.md).

## Citation

If you use this software, please cite the associated JOSS paper:

```
@article{scarlet2, 
    author = {Melchior, Peter and Ward, Charlotte and Remy, Benjamin and Wiemann, Matt L. and Siegel, Jared}, 
    title = {scarlet2: Astronomical scene modeling in JAX}, 
    journal = {Journal of Open Source Software},
    year = {2026}, 
    volume = {11}, 
    number = {120}, 
    pages = {9646}, 
    doi = {10.21105/joss.09646}, 
    url = {https://doi.org/10.21105/joss.09646}, 
    publisher = {The Open Journal} 
}
```