rretc 0.1.0__tar.gz

rretc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 galtavilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rretc-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+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
+```

rretc-0.1.0/README.md

@@ -0,0 +1,114 @@
+# 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
+```

rretc-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rretc"
+version = "0.1.0"
+description = "LBT/LBC point-source exposure-time calculator"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = []
+
+[project.optional-dependencies]
+cli = [
+    "click>=8.4.2",
+]
+
+[project.scripts]
+rretc = "rretc._entrypoint:main"
+
+[dependency-groups]
+dev = [
+    "black>=26.5.1",
+    "click>=8.4.2",
+    "isort>=8.0.1",
+    "pytest>=9.1.1",
+]
+
+[tool.black]
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"

rretc-0.1.0/rretc/__init__.py

@@ -0,0 +1,11 @@
+"""LBT/LBC point-source exposure-time calculator."""
+
+from .core import msat, nexp, snr, texp, tsat
+
+__all__ = [
+    "msat",
+    "nexp",
+    "snr",
+    "texp",
+    "tsat",
+]

rretc-0.1.0/rretc/_entrypoint.py

@@ -0,0 +1,18 @@
+"""Launcher for the optional command-line interface."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    """Run the CLI or explain how to install its optional dependency."""
+    try:
+        from .cli import main as cli_main
+    except ModuleNotFoundError as error:
+        if error.name == "click":
+            raise SystemExit(
+                "The rretc CLI requires `click` as an optional dependency: "
+                'pip install "rretc[cli]"'
+            ) from None
+        raise
+
+    cli_main()

rretc-0.1.0/rretc/cli.py

@@ -0,0 +1,186 @@
+"""Command-line interface for :mod:`rretc`."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import math
+from typing import Any, TypeVar
+
+import click
+
+from .core import (
+    BANDS,
+    SITE_QUALITIES,
+    msat,
+    nexp,
+    snr,
+    texp,
+    tsat,
+)
+
+_Command = TypeVar("_Command", bound=Callable[..., Any])
+_POSITIVE_FLOAT = click.FloatRange(min=0.0, min_open=True)
+
+
+def _finite_float(
+    _: click.Context, param: click.Parameter, value: float
+) -> float:
+    """Reject non-finite floating-point command-line values."""
+    if not math.isfinite(value):
+        raise click.BadParameter("must be a finite number", param=param)
+    return value
+
+
+def _observing_options(
+    *, include_magnitude: bool = True, include_aperture: bool = True
+) -> Callable[[_Command], _Command]:
+    """Return the observing-condition options needed by a CLI command."""
+    options = [
+        click.option(
+            "--seeing",
+            type=_POSITIVE_FLOAT,
+            default=0.75,
+            show_default=True,
+            help="Seeing FWHM in arcseconds.",
+        ),
+        click.option(
+            "--site-quality",
+            type=click.Choice(SITE_QUALITIES, case_sensitive=True),
+            default="ultra-clean",
+            show_default=True,
+            help="Atmospheric aerosol profile.",
+        ),
+        click.option(
+            "--airmass",
+            type=_POSITIVE_FLOAT,
+            default=1.3,
+            show_default=True,
+            help="Target airmass.",
+        ),
+        click.option(
+            "--moon-elongation",
+            type=click.FloatRange(0.0, 180.0),
+            required=True,
+            help="Target-Moon angular separation in degrees.",
+        ),
+        click.option(
+            "--moon-phase",
+            type=click.FloatRange(0.0, 1.0),
+            required=True,
+            help="Lunar phase: 0 is new Moon and 1 is full Moon.",
+        ),
+        click.option(
+            "--moon-zd",
+            type=click.FloatRange(0.0, 180.0),
+            required=True,
+            help="Lunar zenith distance in degrees; >=90 is below the horizon.",
+        ),
+        click.option(
+            "--band",
+            type=click.Choice(BANDS, case_sensitive=True),
+            required=True,
+            help="LBT/LBC photometric band.",
+        ),
+    ]
+    if include_aperture:
+        options.append(
+            click.option(
+                "--aperture",
+                type=_POSITIVE_FLOAT,
+                required=True,
+                help="Photometric aperture diameter in arcseconds.",
+            )
+        )
+    if include_magnitude:
+        options.append(
+            click.option(
+                "--magnitude",
+                type=click.FLOAT,
+                callback=_finite_float,
+                required=True,
+                help="Source magnitude, Vega for UBVRI and AB for ugriz.",
+            )
+        )
+
+    def decorator(command: _Command) -> _Command:
+        for option in options:
+            command = option(command)
+        return command
+
+    return decorator
+
+
+@click.group()
+def main() -> None:
+    """Calculate LBT/LBC point-source exposure times and SNR."""
+
+
+@main.command("nexp")
+@click.option("--snr", type=_POSITIVE_FLOAT, required=True, help="Target SNR.")
+@click.option(
+    "--texp",
+    type=_POSITIVE_FLOAT,
+    required=True,
+    help="Duration of each exposure in seconds.",
+)
+@_observing_options()
+def nexp_command(snr: float, texp: float, **conditions: Any) -> None:
+    """Calculate the minimum exposure count for a target SNR and exposure duration."""
+    click.echo(nexp(snr, texp, **conditions))
+
+
+@main.command("texp")
+@click.option(
+    "--nexp",
+    type=click.IntRange(min=1),
+    required=True,
+    help="Number of individual exposures.",
+)
+@click.option("--snr", type=_POSITIVE_FLOAT, required=True, help="Target SNR.")
+@_observing_options()
+def texp_command(nexp: int, snr: float, **conditions: Any) -> None:
+    """Calculate the minimum exposure duration for a target SNR and exposure count."""
+    click.echo(texp(nexp, snr, **conditions))
+
+
+@main.command("snr")
+@click.option(
+    "--texp",
+    type=_POSITIVE_FLOAT,
+    required=True,
+    help="Duration of each exposure in seconds.",
+)
+@click.option(
+    "--nexp",
+    type=click.IntRange(min=1),
+    required=True,
+    help="Number of individual exposures.",
+)
+@_observing_options()
+def snr_command(texp: float, nexp: int, **conditions: Any) -> None:
+    """Calculate the SNR for a single-exposure duration and exposure count."""
+    click.echo(snr(texp, nexp, **conditions))
+
+
+@main.command("tsat")
+@_observing_options(include_aperture=False)
+def tsat_command(**conditions: Any) -> None:
+    """Calculate the duration at which a source saturates the peak pixel."""
+    click.echo(tsat(**conditions))
+
+
+@main.command("msat")
+@click.option(
+    "--texp",
+    type=_POSITIVE_FLOAT,
+    required=True,
+    help="Duration of one exposure in seconds.",
+)
+@_observing_options(include_magnitude=False, include_aperture=False)
+def msat_command(texp: float, **conditions: Any) -> None:
+    """Calculate the magnitude at which a source saturates the peak pixel."""
+    click.echo(msat(texp, **conditions))
+
+
+if __name__ == "__main__":
+    main()