Metadata-Version: 2.4
Name: rretc
Version: 0.1.0
Summary: LBT/LBC point-source exposure-time calculator
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Provides-Extra: cli
Requires-Dist: click>=8.4.2; extra == 'cli'
Description-Content-Type: text/markdown

# rretc

The _Rapid Response Exposure Time Calculator_ is an exposure-time calculator for point sources observed with LBT/LBC.

## Installation

Install (no dependencies) with:

```bash
pip install .
```

Install the optional command-line interface with:

```bash
pip install ".[cli]"
```

## Python API

The package exposes five functions:

```python
from rretc import msat, nexp, snr, texp, tsat

conditions = {
    "magnitude": 22.0,
    "band": "g",
    "moon_zd": 60.0,
    "moon_phase": 0.0,
    "moon_elongation": 90.0,
    "aperture": 2.25,
    "airmass": 1.3,
    "site_quality": "ultra-clean",
    "seeing": 0.75,
}

count = nexp(100.0, 60.0, **conditions)
seconds = texp(10, 100.0, **conditions)
achieved = snr(60.0, 10, **conditions)

saturation_conditions = {
    key: value
    for key, value in conditions.items()
    if key not in {"magnitude", "aperture"}
}
saturation_time = tsat(18.0, **saturation_conditions)
saturation_magnitude = msat(10.0, **saturation_conditions)
```

`nexp` returns the minimum exposure count for a target SNR and exposure duration;
`texp` returns the minimum exposure duration for a target SNR and exposure count;
and `snr` computes the SNR for an exposure stack. `texp` returns `math.inf` if
the requested SNR is above the systematic-noise limit for the specified number
of exposures.
`tsat` returns the exposure time at which the peak pixel saturates; `msat`
returns the corresponding saturation magnitude for a proposed exposure time.
Both use 90% of the detector full-well capacity. `msat` returns `math.nan`
when sky and dark current alone saturate the pixel.

## Command line

The CLI requires [click](https://click.palletsprojects.com/en/stable/) or the `cli` installation extra (`pip install ".[cli]"`). It provides one subcommand for each API operation and prints one numeric value:

```bash
rretc nexp --snr 100 --texp 60 \
  --magnitude 22 --band g --moon-zd 60 --moon-phase 0 \
  --moon-elongation 90 --aperture 2.25

rretc texp --nexp 10 --snr 100 \
  --magnitude 22 --band g --moon-zd 60 --moon-phase 0 \
  --moon-elongation 90 --aperture 2.25

rretc snr --texp 60 --nexp 10 \
  --magnitude 22 --band g --moon-zd 60 --moon-phase 0 \
  --moon-elongation 90 --aperture 2.25

rretc tsat --magnitude 18 --band V --moon-zd 70 --moon-phase 0.75 \
  --moon-elongation 90

rretc msat --texp 10 --band V --moon-zd 70 --moon-phase 0.75 \
  --moon-elongation 90
```

Run `rretc COMMAND --help` for all options.

## Inputs and assumptions

- Supported bands are `U`, `B`, `V_B`, `V`, `R`, `I`, `u`, `g`, `r_B`, `r`, `i`, and `z`.
- Magnitudes are finite values, Vega for Johnson-Cousins bands and AB for Sloan bands.
- Exposure times are seconds. Lunar angles are degrees. Seeing and aperture are arcseconds.
- Saturation calculations use the central pixel, so `tsat` and `msat` do not
  take an aperture.
- `moon_phase` ranges from 0 for new Moon to 1 for full Moon.
- `moon_zd >= 90` places the Moon below the horizon.
- Site profiles are `standard`, `dry`, and `ultra-clean`.
- Default airmass is 1.3, default site quality is `ultra-clean`, and default seeing is 0.75 arcseconds.

The lunar sky model follows Krisciunas & Schaefer, *PASP* 103, 1033 (1991). The lunar airmass approximation follows Young, *Applied Optics* 33, 1108 (1994).


## Testing and development

Install with:

```shell
pip install . --group dev
```

Run tests with:

```shell
python -m pytest
```
