add image simulation notebook

# You can set these variables from the command line, and also

# from the environment for the first two.

SPHINXOPTS    ?= -j auto

SPHINXOPTS    ?= -j 1

SPHINXBUILD   ?= sphinx-build

SOURCEDIR     = .

BUILDDIR      = build

Notebooks

========================================================================================

.. toctree::

    notebooks/create_truth_catalog

%% Cell type:markdown id:17d2c98b-3ca6-444f-8c94-7708994716d5 tags:

# Simulate example images

This notebooks demonstrates how to use the AGILE truth catalog in order to simulate synthetic LSST images.

We use imSim (https://lsstdesc.org/imSim/index.html) to simulate the images. The purpose of this notebook is not to doucment the feature of imSim, but only to demonstrate how to pass our truth catalog as input to imSim, and how to run software using the tools available in AGILE. Note that imSim only simulates raw LSSTCam data (incl. e.g. sky and instrumental noise), which are not science ready products. The raw images are processed in subsequent steps by using the LSST Science pipelines.

Below, we provide helpful links and resources to further understand the LSST survey, LSSTCam, and the survey strategy.

+ VRO survey strategy: https://survey-strategy.lsst.io/

+ opSim: https://usdf-maf.slac.stanford.edu/

+ imSim: https://lsstdesc.org/imSim/index.html

+ LSSTCam: https://ctn-001.lsst.io/

+ LSSTCam detector layout: https://lsstdesc.org/imSim/lsst-camera.html

The following notebook may be accessed [here](https://www.ict.inaf.it/gitlab/akke.viitanen/lsst_inaf_agile/-/blob/a619e4244f56e731d11724f8a70dd5e7d6e1fda4/docs/notebooks/simulate-images.ipynb)

%% Cell type:code id:e477fcf1-616c-4f80-9397-f0515d03897f tags:

``` python

import os

if not os.path.exists("src/lsst_inaf_agile"):

    os.chdir("../../")

    os.getcwd()

```

%% Cell type:code id:bf04619d-6be2-466a-8ab4-bb89dfad1ee8 tags:

``` python

import logging

import numpy as np

from lsst_inaf_agile.catalog_agn import CatalogAGN

from lsst_inaf_agile.catalog_combined import CatalogCombined

from lsst_inaf_agile.catalog_galaxy import CatalogGalaxy

from lsst_inaf_agile.catalog_star import CatalogStar

from lsst_inaf_agile.egg import Egg

from lsst_inaf_agile.image_simulator import ImageSimulator

from lsst_inaf_agile.merloni2014 import Merloni2014

from lsst_inaf_agile import util

```

%% Cell type:markdown id:8bca37d1-ee74-4e11-9719-74ebaae1ded4 tags:

## Create a combined truth catalog for testing purposes

%% Cell type:code id:74e34a70-3255-47cd-8ae2-fcdec07ccf7a tags:

``` python

def get_catalog_combined(dirname):

    """Return a test CatalogCombined object."""

    os.makedirs(dirname, exist_ok=True)

    # Create a combined truth catalog

    egg_kwargs = Egg.get_example_egg_kwargs(dirname + "/egg.fits")

    print(egg_kwargs)

    egg = Egg(egg_kwargs)

    egg.run()

    catalog_egg = Egg.read(egg_kwargs["out"])

    catalog_galaxy = CatalogGalaxy(dirname, catalog_egg)

    catalog_agn = CatalogAGN(

        dirname=dirname,

        catalog_galaxy=catalog_galaxy,

        type_plambda="zou+2024",

        save_sed=1,

        seed=20250621,

        merloni2014=Merloni2014(1, 0, 0.05, 0.95),

    )

    catalog_star = CatalogStar(dirname, catalog_galaxy, is_binary=False)

    catalog_binary = CatalogStar(dirname, catalog_galaxy, is_binary=True)

    # Create the combined catalog

    catalog_combined = CatalogCombined(dirname, catalog_galaxy, catalog_agn, catalog_star, catalog_binary)

    assert np.isclose(catalog_combined.get_area(), 0.01)

    return catalog_combined

```

%% Cell type:code id:f3cba3e2-5d32-4706-a3ce-ae28e5484c8b tags:

``` python

# Get the combined catalog

dirname = "data/catalog/test"

catalog_combined = get_catalog_combined(dirname)

```

%% Cell type:markdown id:10307a9b-3d77-4147-a305-98526fb24abb tags:

## Initialize the ImageSimulator

%% Cell type:code id:cd596c55-b97d-4ff3-b181-7ee6e6221460 tags:

``` python

# Select a baseline

# NOTE: https://usdf-maf.slac.stanford.edu/

filename_baseline = "data/baseline/baseline_v4.0_10yrs.db"

image_simulator = ImageSimulator(f"{dirname}/imsim", catalog_combined, filename_baseline)

```

%% Cell type:markdown id:82125a9a-92a5-4701-be7d-20d31d15994b tags:

## Explore the visits database

%% Cell type:code id:2cb4c824-b66b-4afc-abda-e5ab4822f65a tags:

``` python

visits = image_simulator.get_visit()

visits.info()

```

%% Cell type:code id:65bcfc00-50ff-4559-9d37-ebcab46de633 tags:

``` python

visits[:5]

```

%% Cell type:code id:7ca30458-4dc3-41e7-b71b-35b880028dba tags:

``` python

observation_id = 779

ra_dec = +150.11916667, +2.20583333

image_simulator.write_instance_catalog(observation_id, ra_dec=ra_dec)

```

%% Cell type:markdown id:aa6b1314-e140-45c8-abd1-310911803782 tags:

## Simulate a single visit and single detector

%% Cell type:code id:b5cca004-9a7f-408e-8176-6030532f1e1e tags:

``` python

detector = 94

image_simulator.simulate_image(observation_id=observation_id, detector=detector)

```

%% Cell type:markdown id:834cc687-1f88-4b24-a327-ee6091ae3821 tags:

## Explore the output products

%% Cell type:code id:63e9a2c5-523e-4be3-aaa1-a7ca0838071c tags:

``` python

dirname_output = os.path.join(dirname, "imsim", str(observation_id), "output")

print("Dirname_output is {dirname_output}")

```

%% Cell type:code id:e7b26a2e-0b43-4472-9ed9-00d8d2e3c1c2 tags:

``` python

os.listdir(dirname_output)

```

%% Cell type:markdown id:ab2afdcf-f770-4940-8225-55bc525a37c5 tags:

## On simulating multiple images and/or detectors

Simulating any large dataset is a computationally expensive task. To simulate any significantly large dataset (such as the AGILE DR1), one is adviced to wrap the `image_simulator.simulate_image` into a callable script which could be executed with multiple cores and/or threads. In AGILE DR1, this orchestration was done with slurm (https://slurm.schedmd.com/documentation.html).

.. toctree::

    notebooks/create_truth_catalog

    notebooks/simulate_images

        filename = f"{self.dirname}/lightcurves/agn/{i}/{band}.npy"

        if os.path.exists(filename):

            logger.info(f"Reading AGN lightcurve {filename}")

            logger.debug(f"Reading AGN lightcurve {filename}")

            return np.load(filename)

        mjd = util.get_mjd_vec()