lfast-etc 0.1.0__py3-none-any.whl

lfast_etc/__init__.py

@@ -0,0 +1,27 @@
+"""lfast_etc: Exposure Time Calculator for the LFAST telescope array.
+
+Quick start::
+
+    from lfast_etc import LFASTETC, Source
+    etc = LFASTETC("bench_r1800", n_telescopes=20)
+    src = Source.blackbody(5800, mag=15, band="V")
+    res = etc.exptime(src, snr=50)
+    res.plot()
+"""
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("lfast-etc")
+except importlib.metadata.PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+from .instrument import Instrument, list_instruments
+from .telescope import Telescope
+from .source import Source, BANDS
+from .sky import Sky
+from .etc import LFASTETC, ETCResult
+
+__all__ = [
+    "__version__", "LFASTETC", "ETCResult", "Instrument", "list_instruments",
+    "Telescope", "Source", "Sky", "BANDS",
+]

lfast_etc/constants.py

@@ -0,0 +1,23 @@
+"""Physical constants (SI) and package data paths."""
+from pathlib import Path
+import numpy as np
+
+H_PLANCK = 6.62607015e-34   # J s
+C_LIGHT = 2.99792458e8      # m/s
+K_BOLTZMANN = 1.380649e-23  # J/K
+
+DATA_DIR = Path(__file__).parent / "data"
+
+
+def positive(name, value, allow_zero=False):
+    """Validate a scalar parameter at the public boundary; returns it as float."""
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        raise ValueError(f"{name} must be a number, got {value!r}") from None
+    if not np.isfinite(v) or v < 0 or (v == 0 and not allow_zero):
+        raise ValueError(f"{name} must be {'>= 0' if allow_zero else '> 0'}, got {value!r}")
+    return v
+THROUGHPUT_DIR = DATA_DIR / "throughput"
+SKY_DIR = DATA_DIR / "sky"
+CONFIG_DIR = DATA_DIR / "config"

lfast_etc/data/config/bench_1200_28p7_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 1200 @ 28.7 grating, order 1, blaze peak 7500 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 1231 A, red-cable resolution 1.19 A at 2x2 binning.
+[instrument]
+name = "bench_1200_28p7_o1"
+description = "WIYN Bench, 1200 @ 28.7 deg, order 1, 688-812 nm, R~6910"
+wavelength_min_nm = 688.5
+wavelength_max_nm = 811.5
+resolving_power = 6910
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.229  # grating peak efficiency 55% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_1200_28p7_o2.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 1200 @ 28.7 grating, order 2, blaze peak 4000 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 615 A, red-cable resolution 0.58 A at 2x2 binning.
+[instrument]
+name = "bench_1200_28p7_o2"
+description = "WIYN Bench, 1200 @ 28.7 deg, order 2, 400-431 nm, R~7560 (clipped at 400 nm)"
+wavelength_min_nm = 400.0
+wavelength_max_nm = 430.8
+resolving_power = 7561
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.229  # grating peak efficiency 55% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_316_63p4_o9.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 316 @ 63.4 grating, order 9, blaze peak 6563 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 250 A, red-cable resolution 0.23 A at 2x2 binning.
+[instrument]
+name = "bench_316_63p4_o9"
+description = "WIYN Bench, 316 @ 63.4 deg, order 9, 644-669 nm, R~31280"
+wavelength_min_nm = 643.8
+wavelength_max_nm = 668.8
+resolving_power = 31284
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.208  # grating peak efficiency 50% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_316_7p0_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 316 @ 7.0 grating, order 1, blaze peak 7500 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 5290 A, red-cable resolution 5.72 A at 2x2 binning.
+[instrument]
+name = "bench_316_7p0_o1"
+description = "WIYN Bench, 316 @ 7.0 deg, order 1, 486-1014 nm, R~1440"
+wavelength_min_nm = 485.5
+wavelength_max_nm = 1014.5
+resolving_power = 1438
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.292  # grating peak efficiency 70% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_316_7p0_o2.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 316 @ 7.0 grating, order 2, blaze peak 3750 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 2645 A, red-cable resolution 2.86 A at 2x2 binning.
+[instrument]
+name = "bench_316_7p0_o2"
+description = "WIYN Bench, 316 @ 7.0 deg, order 2, 400-507 nm, R~1440 (clipped at 400 nm)"
+wavelength_min_nm = 400.0
+wavelength_max_nm = 507.2
+resolving_power = 1438
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.292  # grating peak efficiency 70% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_3300vph_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 3300 VPH grating, order 1, blaze peak 5120 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 273 A, red-cable resolution 0.31 A at 2x2 binning.
+[instrument]
+name = "bench_3300vph_o1"
+description = "WIYN Bench, 3300 VPH, order 1, 498-526 nm, R~18110"
+wavelength_min_nm = 498.4
+wavelength_max_nm = 525.6
+resolving_power = 18108
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.300  # no peak efficiency listed for the VPH gratings: anchor value kept
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_400_4p2_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 400 @ 4.2 grating, order 1, blaze peak 5000 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 4199 A, red-cable resolution 4.56 A at 2x2 binning.
+[instrument]
+name = "bench_400_4p2_o1"
+description = "WIYN Bench, 400 @ 4.2 deg, order 1, 400-710 nm, R~1200 (clipped at 400 nm) (not recommended by WIYN: hard to focus over the range)"
+wavelength_min_nm = 400.0
+wavelength_max_nm = 710.0
+resolving_power = 1202
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.292  # grating peak efficiency 70% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_600_13p9_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 600 @ 13.9 grating, order 1, blaze peak 7500 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 2724 A, red-cable resolution 2.86 A at 2x2 binning.
+[instrument]
+name = "bench_600_13p9_o1"
+description = "WIYN Bench, 600 @ 13.9 deg, order 1, 614-886 nm, R~2880"
+wavelength_min_nm = 613.8
+wavelength_max_nm = 886.2
+resolving_power = 2875
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.292  # grating peak efficiency 70% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_600_13p9_o2.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 600 @ 13.9 grating, order 2, blaze peak 3800 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 1362 A, red-cable resolution 1.43 A at 2x2 binning.
+[instrument]
+name = "bench_600_13p9_o2"
+description = "WIYN Bench, 600 @ 13.9 deg, order 2, 400-448 nm, R~2910 (clipped at 400 nm)"
+wavelength_min_nm = 400.0
+wavelength_max_nm = 448.1
+resolving_power = 2913
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.292  # grating peak efficiency 70% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_740vph_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 740 VPH grating, order 1, blaze peak 8798 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 2152 A, red-cable resolution 2.68 A at 2x2 binning.
+[instrument]
+name = "bench_740vph_o1"
+description = "WIYN Bench, 740 VPH, order 1, 772-987 nm, R~3600"
+wavelength_min_nm = 772.2
+wavelength_max_nm = 987.4
+resolving_power = 3599
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.300  # no peak efficiency listed for the VPH gratings: anchor value kept
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_740vph_o2.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 740 VPH grating, order 2, blaze peak 5000 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 1076 A, red-cable resolution 1.34 A at 2x2 binning.
+[instrument]
+name = "bench_740vph_o2"
+description = "WIYN Bench, 740 VPH, order 2, 446-554 nm, R~4090"
+wavelength_min_nm = 446.2
+wavelength_max_nm = 553.8
+resolving_power = 4091
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.300  # no peak efficiency listed for the VPH gratings: anchor value kept
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_860_30p9_o1.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 860 @ 30.9 grating, order 1, blaze peak 10800 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 1680 A, red-cable resolution 1.64 A at 2x2 binning.
+[instrument]
+name = "bench_860_30p9_o1"
+description = "WIYN Bench, 860 @ 30.9 deg, order 1, 996-1164 nm, R~7220"
+wavelength_min_nm = 996.0
+wavelength_max_nm = 1164.0
+resolving_power = 7220
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.271  # grating peak efficiency 65% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_860_30p9_o2.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 860 @ 30.9 grating, order 2, blaze peak 6000 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 840 A, red-cable resolution 0.77 A at 2x2 binning.
+[instrument]
+name = "bench_860_30p9_o2"
+description = "WIYN Bench, 860 @ 30.9 deg, order 2, 558-642 nm, R~8540"
+wavelength_min_nm = 558.0
+wavelength_max_nm = 642.0
+resolving_power = 8543
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.271  # grating peak efficiency 65% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_860_30p9_o3.toml

@@ -0,0 +1,18 @@
+# WIYN Bench spectrograph, 860 @ 30.9 grating, order 3, blaze peak 4000 A.
+# Row of https://www.wiyn.org/Instruments/wiynbench.html; generated by
+# scripts/build_bench_presets.py from the bench_r1800 anchor (see that script).
+# Table coverage 560 A, red-cable resolution 0.52 A at 2x2 binning.
+[instrument]
+name = "bench_860_30p9_o3"
+description = "WIYN Bench, 860 @ 30.9 deg, order 3, 400-428 nm, R~8430 (clipped at 400 nm)"
+wavelength_min_nm = 400.0
+wavelength_max_nm = 428.0
+resolving_power = 8434
+pixels_per_resel = 2.2    # dispersion direction only, as bench_r1800
+spectrograph_efficiency = 0.271  # grating peak efficiency 65% vs 72% for the 600 @ 10.1 anchor
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE, as bench_r1800
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/bench_r1800.toml

@@ -0,0 +1,20 @@
+# WIYN Bench spectrograph, sample moderate-resolution visible configuration.
+# 600 lpm grating @ 10.1 deg, lambda_central = 5500 A, delta_lambda = 2763 A.
+# Only 1-2 Bench configurations will be offered at the start of operations;
+# the spectrograph cannot be reconfigured during the night. LFAST uses 1x1 binning.
+# The other Bench modes (bench_*.toml) are generated from this one by
+# scripts/build_bench_presets.py from the WIYN configuration table.
+[instrument]
+name = "bench_r1800"
+description = "WIYN Bench, 600 @ 10.1 deg, order 1, 412-686 nm, R~1800 (reference notebook)"
+wavelength_min_nm = 412.0
+wavelength_max_nm = 686.0   # config spans to 688 nm; K_opt drops to ~5e-9 at 687 nm (O2 B band)
+resolving_power = 1800.0
+pixels_per_resel = 2.2    # dispersion direction only (reference notebook); x fiber-image height when known
+spectrograph_efficiency = 0.3
+slit_throughput = 1.0
+qe = 0.75              # placeholder flat QE
+dark_current = 3.0e-4  # e-/s/pix
+read_noise = 3.7       # e-/pix
+full_well = 100000.0   # placeholder
+min_exptime = 1.0

lfast_etc/data/config/cshell_r18000.toml

@@ -0,0 +1,19 @@
+# CSHELL, native resolution using the input fiber alone (no slit).
+# CSHELL covers ~1.08-1.75 um. Free spectral range is small: ~2.5e-3 lambda
+# (39 A at 1.555 um, 27 A at 1.08 um, 44 A at 1.75 um), so one setup covers
+# only a narrow window; set wavelength limits to the window of interest.
+[instrument]
+name = "cshell_r18000"
+description = "CSHELL, native fiber resolution R=18,000, 1.08-1.75 um"
+wavelength_min_nm = 1080.0
+wavelength_max_nm = 1750.0
+resolving_power = 18000.0
+pixels_per_resel = 2.5    # dispersion direction only (reference notebook); x fiber-image height when known
+spectrograph_efficiency = 0.1
+slit_throughput = 1.0
+qe = 0.8               # placeholder flat QE
+dark_current = 0.5     # e-/s/pix
+read_noise = 22.0      # e-/pix, Fowler sampling with total exposure > 8 s
+full_well = 80000.0    # placeholder
+min_exptime = 8.0
+free_spectral_range_frac = 2.5e-3

lfast_etc/data/config/cshell_r21500.toml

@@ -0,0 +1,17 @@
+# CSHELL with the 200 um slit. Slit throughput loss is TBD ("XX%" in the
+# reference notebook); 0.75 is a placeholder -- update when measured.
+[instrument]
+name = "cshell_r21500"
+description = "CSHELL, 200 um slit, R=21,500, 1.08-1.75 um (slit loss placeholder)"
+wavelength_min_nm = 1080.0
+wavelength_max_nm = 1750.0
+resolving_power = 21500.0
+pixels_per_resel = 2.5    # dispersion direction only (reference notebook); x fiber-image height when known
+spectrograph_efficiency = 0.1
+slit_throughput = 0.75   # PLACEHOLDER
+qe = 0.8
+dark_current = 0.5
+read_noise = 22.0
+full_well = 80000.0
+min_exptime = 8.0
+free_spectral_range_frac = 2.5e-3

lfast_etc/data/config/cshell_r43000.toml

@@ -0,0 +1,17 @@
+# CSHELL with the 100 um slit. Slit throughput loss is TBD ("YY%" in the
+# reference notebook); 0.5 is a placeholder -- update when measured.
+[instrument]
+name = "cshell_r43000"
+description = "CSHELL, 100 um slit, R=43,000, 1.08-1.75 um (slit loss placeholder)"
+wavelength_min_nm = 1080.0
+wavelength_max_nm = 1750.0
+resolving_power = 43000.0
+pixels_per_resel = 2.5    # dispersion direction only (reference notebook); x fiber-image height when known
+spectrograph_efficiency = 0.1
+slit_throughput = 0.5    # PLACEHOLDER
+qe = 0.8
+dark_current = 0.5
+read_noise = 22.0
+full_well = 80000.0
+min_exptime = 8.0
+free_spectral_range_frac = 2.5e-3