Metadata-Version: 2.4
Name: simulit
Version: 0.1.0
Summary: Simulate UVIT-like photon event lists from astrophysical source models
Project-URL: Homepage, https://github.com/prajwel/simulit
Project-URL: Issues, https://github.com/prajwel/simulit/issues
Author-email: Prajwel Joseph <prajwel.pj@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: AstroSat,UVIT,astronomy,detector,event list,photon,simulation
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.9
Requires-Dist: astropy
Requires-Dist: numpy
Description-Content-Type: text/markdown

# Simulit

Simulit is a Python package for simulating UVIT-like photon event lists from astrophysical source models.

It is designed for developing, testing, and validating software for source detection, photometry, variability analysis, PSF improvement, and other UVIT data analysis applications.

Current source models include:

- Gaussian point sources
- Elliptical exponential galaxies
- Uniform circular sources

Simulit can also:

- Generate detector images from simulated event lists
- Create truth catalogues for validation and benchmarking
- Inject simulated events into existing UVIT Level-2 event lists

## Installation

```bash
pip install simulit
```

## Quick start

```python
import numpy as np
import simulit as sm

rng = np.random.default_rng(42)

observation = sm.Observation(
    exposure=2000,
)

centre = observation.detector.detector_size / 2

sources = sm.generate_sources(
    n_sources=100,
    rate=0.1,
    fwhm=1.2,
    x0=centre,
    y0=centre,
    radius=2048,
    rng=rng,
)

times, x, y = observation.simulate_events(
    sources,
    rng=rng,
)

truth = sm.create_truth_catalogue(sources)

sm.save_events_to_fits(times, x, y)
sm.save_truth_catalogue(truth)

sm.make_image_from_events(
    x,
    y,
    exposure=observation.exposure,
    detector_size=observation.detector.detector_size,
)
```

## Source models

### GaussianSource

A Gaussian point source.

```python
sm.GaussianSource(
    rate=1.0,
    x=2400,
    y=2400,
    fwhm=1.2,
)
```

### ExponentialGalaxy

An elliptical exponential galaxy with an exponential surface brightness profile.

```python
sm.ExponentialGalaxy(
    rate=0.5,
    x=2400,
    y=2400,
    r0=3.0,
    q=0.7,
    pa=np.pi / 4,
)
```

### UniformDisk

A uniformly illuminated circular source.

```python
sm.UniformDisk(
    rate=5.0,
    x=2400,
    y=2400,
    radius=200,
)
```

## Observation

An `Observation` combines

- exposure time
- detector configuration
- optional pointing drift

```python
observation = sm.Observation(
    exposure=2000,
)
```

A pointing drift model can also be supplied.

```python
drift = sm.Drift(
    x_offset=x_shift,
    y_offset=y_shift,
)

observation = sm.Observation(
    exposure=2000,
    drift=drift,
)
```

## Output products

Simulit can generate

- simulated photon event lists
- detector images
- truth catalogues

It can also append simulated events to an existing UVIT Level-2 event list, enabling realistic testing of UVIT analysis software.

## Examples

The `examples/` directory contains complete working examples.

- `mixed_sources.py` — mixed populations of point sources, galaxies, and diffuse background
- `synthetic_drift.py` — simulate observations with synthetic UVIT-inspired pointing drift

## Planned features

Future development is expected to include:

- additional source models
- realistic background models
- cosmic ray simulations
- detector artefacts
- UVIT slitless spectroscopy
- filter-dependent simulations
- additional validation datasets
