PyDIET 0.9.3__py3-none-any.whl

pydiet/server/models/query.py

@@ -0,0 +1,172 @@
+"""
+Query models
+"""
+# Copyright CFHT/CNRS/CEA/UParisSaclay
+# Licensed under the MIT licence
+
+from typing import Literal
+from pydantic import (
+    BaseModel,
+    Field,
+    PydanticUserError,
+    ValidationInfo,
+    field_validator
+)
+
+from .default import default_filter, default_instrument, filters, instruments
+from .exceptions import ETCValidationError
+from .types import (
+    ComputeID,
+    FilterID,
+    InstrumentID,
+    PhotometryID,
+    PhotSysID,
+    SkyID,
+    SourceID,
+    StackingID
+)
+
+class ETCQueryModel(BaseModel):
+
+    instrument: InstrumentID = Field(
+        default=default_instrument.id,
+        description="Instrument ID"
+    )
+
+    airmass: float = Field(
+        default=1.2,
+        ge=1.,
+        description="Observation airmass"
+    )
+
+    aperture: float = Field(
+        default=3.,
+        gt=0.,
+        le=15.,
+        description="Photometric aperture diameter [\"]"
+    )
+
+    brightness: float = Field(
+        default=20.,
+        ge=-100.,
+        le=1000.,
+        description="Source brightness"
+    )
+
+    compute: ComputeID = Field(
+        default='etime',
+        description="Computation type"
+    )
+
+    etime: float = Field(
+        default=20.,
+        ge=0.,
+        le=1e30,
+        description="Exposure time [s]"
+    )
+
+    exposures: int = Field(
+        default=1,
+        ge=1,
+        le=1000000,
+        description="Number of exposures"
+    )
+
+    filter: FilterID = Field(
+        default=default_filter,
+        description="Instrument filter"
+    )
+
+    photometry: PhotometryID = Field(
+        default='model_fitting',
+        description="Photometry type"
+    )
+
+    seeing: float = Field(
+        default=0.7,
+        ge=0.1,
+        le=100.
+    )
+
+    sky: SkyID = Field(
+        default='dark',
+        description="Sky setting"
+    )
+
+    sky_brightness: float = Field(
+        default=22.,
+        ge=-100.,
+        le=1000.,
+        description="Sky surface brightness"
+    )
+
+    sersic_radius: float = Field(
+        default=1.,
+        gt=0.,
+        le=10.,
+        description="Sérsic effective radius [\"]"
+    )
+
+    sersic_index: float = Field(
+        default=1.,
+        ge=0.3,
+        le=10.,
+        description="Sérsic index"
+    )
+
+    sky_unit: PhotSysID = Field(
+        default='abmag',
+        description="Sky background photometric system"
+    )
+
+    snr: float = Field(
+        default=10.,
+        gt=0.,
+        description="Required source Signal-to-Noise Ratio"
+    )
+
+    source: SourceID = Field(
+        default='point_source',
+        description="Source type"
+    )
+
+    stacking: StackingID = Field(
+        default='median',
+        description="Stacking method"
+    )
+
+    transparency: float = Field(
+        default=1.,
+        gt=0.,
+        le=1.,
+        description="Sky transparency"
+    )
+
+    unit: PhotSysID = Field(
+        default='abmag',
+        description="Photometric system"
+    )
+
+    @field_validator('filter')
+    def validate_filter(cls, f: str, info: ValidationInfo) -> str:
+        """
+        Kind of emulate Enum validation and errors.
+        """
+        instrument = info.data['instrument']
+        fids = list(instruments[instrument].filters.transmissions) + ['upload']
+        if f not in fids:
+            expected = f"'{fids[0]}'" + \
+                (
+                    "".join(f", '{fid}'" for fid in fids[:-1]) \
+                    if len(fids) > 2 else ""
+                ) + (
+                    f" or '{fids[-1]}'" if len(fids) > 1 else ""
+                )
+            raise ETCValidationError({
+                "type": "enum",
+                "loc": ("query", "filter"),
+                "input": str(f),
+                "expected": expected
+            })
+        return f
+

pydiet/server/models/response.py

@@ -0,0 +1,97 @@
+"""
+Response models
+"""
+# Copyright CFHT/CNRS/CEA/UParisSaclay
+# Licensed under the MIT licence
+
+from typing import Optional
+
+from astropy import units as u #type: ignore[import-untyped]
+from pydantic import BaseModel, Field, Json
+
+from ..types import AnnotatedQuantity
+from .types import ComputeID, FilterID, InstrumentID
+from .instrument import TransmissionModel
+
+
+class ETCResponseModel(BaseModel):
+
+    instrument: str
+
+    filter: str
+
+    compute: ComputeID
+
+    zp: float=Field(
+        default=0.,
+        ge=-100.,
+        le=100.,
+        description="Estimate magnitude zero-point"
+    )
+
+    snr: float=Field(
+        default=10.,
+        ge=0.,
+        lt=1e30,
+        description="Estimated source Signal-to-Noise Ratio"
+    )
+
+    etime: float=Field(
+        default=1.,
+        ge=0.,
+        lt=1e30,
+        description="Estimated exposure time"
+    )
+
+    etime_skysat: float=Field(
+        default=0.,
+        ge=0.,
+        lt=1e30,
+        description="Estimated exposure time for sky background saturation"
+    )
+
+    etime_sourcesat: float=Field(
+        default=0.,
+        ge=0.,
+        lt=1e30,
+        description="Estimated exposure time for source saturation"
+    )
+
+    ttime: float=Field(
+        default=1.,
+        ge=0.,
+        lt=1e30,
+        description="Estimated total time"
+    )
+
+    sky_mag: float=Field(
+        default=99.,
+        ge=-100.,
+        le=100.,
+        description="Estimated sky background in mag/arcsec2"
+    )
+
+    lambda_pivot: float=Field(
+        default=0.,
+        ge=0.,
+        lt=1e12,
+        description="Pivot wavelength of the full filter response in nm"
+    )
+
+    bandwidth_rect: float=Field(
+        default=0.,
+        ge=0.,
+        lt=1e12,
+        description="Equivalent rectangular bandwidth of the full filter response in nm"
+    )
+
+    cutout: Optional[str]=Field(
+        default=None,
+        description="GIF animation of the source"
+    )
+
+    filter_transmission: Optional[Json] = None
+
+    atmosphere_transmission: Optional[Json] = None
+
+

pydiet/server/models/types.py

@@ -0,0 +1,35 @@
+"""
+Custom types for PyDIET data models
+"""
+# Copyright CFHT/CNRS/CEA/UParisSaclay
+# Licensed under the MIT licence
+
+from enum import Enum
+from typing import Literal
+
+from .default import filters, instruments
+
+ComputeID = Literal['etime', 'snr']
+
+FilterID = Enum(  # type: ignore[misc]
+    "FilterID",
+    {tag : tag for tag in filters.keys()} | {'upload' : 'upload'},
+    type=str
+)
+
+InstrumentID = Enum(  # type: ignore[misc]
+    "InstrumentID",
+    {tag : tag for tag in instruments.keys()},
+    type=str
+)
+
+SkyID = Literal['dark', 'grey', 'bright', 'specify']
+
+PhotometryID = Literal['model_fitting', 'fixed_aperture', 'optimal_aperture', 'large_aperture']
+
+PhotSysID = Literal['abmag', 'vegamag', 'fmegajy', 'fmujy', 'flux', 'photons']
+
+SourceID = Literal['point_source', 'galaxy', 'extended']
+
+StackingID = Literal['average', 'median']
+

pydiet/server/photsys.py

@@ -0,0 +1,71 @@
+"""
+Photometric system conversion module
+"""
+# Copyright CFHT
+# Licensed under the MIT licence
+
+from typing import Optional
+
+from astropy import units as u  #type: ignore[import-untyped]
+
+from .models.types import PhotSysID
+
+from .data import ab_spectrum, vega_spectrum
+
+
+class PhotSys(object):
+    def __init__(
+            self,
+            id: PhotSysID = 'abmag',
+            wavelength: Optional[u.Quantity[u.nm]] =  None,
+            dwavelength: Optional[u.Quantity[u.nm]] = None):
+
+        self.eps = 1e-30
+        self.id = id
+        if id == 'abmag':
+            self.spectrum = ab_spectrum
+            self.photon_rate = self._rate_from_mag
+        elif id == 'vegamag':
+            self.spectrum = vega_spectrum
+            self.photon_rate = self._rate_from_mag  #type: ignore[assignment]
+        elif id == 'fmegajy':
+            self.spectrum = ab_spectrum
+            self.photon_rate = self._rate_from_fmegajy  #type: ignore[assignment]
+        elif id == 'fmujy':
+            self.spectrum = ab_spectrum
+            self.photon_rate = self._rate_from_fmujy  #type: ignore[assignment]
+        elif id == 'flux':
+            self.spectrum = ab_spectrum
+            self.photon_rate = self._rate_from_flux  #type: ignore[assignment]
+            if wavelength is None:
+                raise ValueError("wavelength is required when id == 'flux'")
+            if dwavelength is None:
+                raise ValueError("dwavelength is required when id == 'flux'")
+            self.wavelength = wavelength.to_value(u.nm)
+            self.dwavelength = dwavelength.to_value(u.nm)
+        else:
+            self.spectrum = None
+            self.photon_rate = self._rate_from_photons  #type: ignore[assignment]
+
+
+    def _rate_from_mag(self, mag: float) -> float:
+        return 10.**(-0.4 * mag) if mag < 40. else 1e-16
+
+    def _rate_from_fmegajy(self, fnu: float) -> float:
+        return 2.754e+02 * (fnu if fnu >= self.eps else self.eps)
+
+    def _rate_from_fmujy(self, fnu: float) -> float:
+        return 2.754e-10 * (fnu if fnu >= self.eps else self.eps)
+
+    def _rate_from_flux(self, flux: float) -> float:
+        if self.dwavelength < self.eps:
+            self.dwavelength = self.eps
+        # 10**(0.4*48.6) / 3e17 (in nm/s) = 91.808
+        return 91.808 * self.wavelength ** 2 / self.dwavelength \
+            * (flux if flux >= self.eps else self.eps) * 1e-15
+
+    def _rate_from_photons(self, photons: float) -> float:
+        return photons if photons >= self.eps else self.eps
+
+
+

pydiet/server/response.py

@@ -0,0 +1,237 @@
+"""
+Computation module
+"""
+# Copyright CFHT
+# Licensed under the MIT licence
+
+from math import pi, sqrt
+from os import PathLike
+from typing import IO, Optional
+
+from astropy import units as u  #type: ignore[import-untyped]
+from pydantic import BaseModel, Field
+from synphot import Observation, SpectralElement  #type: ignore[import-untyped]
+
+from .image import Image
+from .models import (
+    ETCQueryModel,
+    ETCResponseModel,
+    FiltersModel,
+    SBSEDModel,
+    SEDModel,
+    TransmissionModel,
+    spectral_to_arrays
+)
+from .models.types import SkyID
+from .data import instruments
+from .datafiles import (
+    get_emission_from_transmission,
+    get_transmission
+)
+from .photsys import PhotSys
+
+
+def spectrum_from_airmass(
+        models: dict[str, SBSEDModel | SEDModel | TransmissionModel],
+        sky: SkyID|None = None,
+        am: float = 1.) -> SpectralElement:
+    # Build a dictionary of emission or transmission spectra
+    am_spectra = {
+        model.vars['am'] : model.spectral  #type: ignore[index]
+        for model in models.values()
+        if sky is None or model.vars['sky'] == sky  #type: ignore[index]
+    }
+    ams = sorted(list(am_spectra.keys()))
+    # bracket the requested airmass for interpolation
+    aml = float(ams[0])
+    amp = float(ams[-1])
+    for aa in ams:
+        a = float(aa)
+        if a >= am:
+            amp = a
+            break
+        else:
+            aml = a
+    # Linear interpolation
+    fac = (am - aml) / (amp - aml) if am < amp else 1.
+    return am_spectra[aml] * (1. - fac) +  am_spectra[amp] * fac  #type: ignore[operator]
+
+
+def get_response(
+        q: ETCQueryModel,
+        filter: Optional[IO[bytes] | PathLike | str]=None,
+        ui: bool=False) -> ETCResponseModel:
+    if filter is not None:
+        # Read the uploaded filter transmission file
+        filter_transmission = get_transmission(filter, id='upload')
+        # Compute filter emission based on transmission (and dummy temperature/area)
+        emission = get_emission_from_transmission(
+            filter_transmission,
+            temperature=273. * u.K,
+            id='upload'
+        )
+        # Make a copy of the instrument while adding the uploaded filter
+        filters = instruments[q.instrument].filters
+        instrument = instruments[q.instrument].model_copy(
+            update={
+                'filters': FiltersModel(
+                    transmissions = filters.transmissions | {
+                        'upload' : filter_transmission
+                    },
+                    emissions = filters.emissions | {'upload' : emission}
+                )
+            }
+        )
+        # Update composite transmissions and emission curves
+        instrument._update_transmissions()
+    else:
+        instrument = instruments[q.instrument]
+
+    telescope = instrument.telescope
+    detector = instrument.detector
+    instrument_transmission = instrument.transmissions[q.filter]
+
+    # Multiply Total instrument transmission with atmospheric transmission
+    atmosphere_spec = spectrum_from_airmass(
+        instrument.site.sky_transmissions,
+        am=q.airmass
+    ) * q.transparency
+    full_spec = instrument_transmission.spectral * atmosphere_spec
+    # Compute effective collecting area, compensating for possible obstruction
+    area = instrument.telescope.collecting_area - instrument.obstruction_area
+
+    # Make virtual observation
+    gain = detector.gain.value
+    tpeak = full_spec.tpeak()
+    lambda_pivot = full_spec.pivot()
+    dlambda_rect = full_spec.rectwidth()
+    # Actual source
+    photsys = PhotSys(q.unit, lambda_pivot, dlambda_rect)
+    if tpeak > 0.:
+        if photsys.spectrum is None:
+            ct_ref = photsys.photon_rate(q.brightness) / gain * u.ct / u.s
+        else:
+            observation = Observation(photsys.spectrum, full_spec)
+            # Compute ref source count rate to get effective zero-point
+            ct_ref = observation.countrate(area=area, binned=False) / gain
+        zp = u.Magnitude(1. * u.ct / u.s) - u.Magnitude(ct_ref)
+    else:
+        ct_ref = 0. * u.ct / u.s
+        zp = -100. * u.mag
+    # Compute total number of reference source electrons (photons per second)
+    photon_rate = (ct_ref * gain).value * photsys.photon_rate(q.brightness)
+
+    # Sky background
+    # Atmospheric emission
+    if q.sky == 'specify':
+        sky_photsys = PhotSys(q.sky_unit, lambda_pivot, dlambda_rect)
+        sky_spectrum = sky_photsys.spectrum
+        sky_photon_rate = sky_photsys.photon_rate(q.sky_brightness)
+        if sky_spectrum is not None:
+            # If in Jy per str, convert to arcsec2
+            if q.sky_unit == 'fmegajy':
+                sky_photon_rate *= 2.350e-11
+            sky_spectrum *= sky_photon_rate
+    else:
+        sky_spectrum = spectrum_from_airmass(
+            instrument.site.sky_emissions,
+            sky=q.sky,
+            am=q.airmass
+        )
+    if sky_spectrum is not None:
+        # Compute background count rate to get background surface brightness
+        if tpeak > 0.:
+            bkg_observation = Observation(
+                sky_spectrum,
+                instrument_transmission.spectral,
+                force='extrap'
+            )
+            # Add instrumental thermal background
+            ct_bkgsb = (
+                bkg_observation.countrate(area=area, binned=False) \
+                + instrument.emissions_ct[q.filter] * u.ct / u.s
+                ) / gain
+            mag_bkgsb = zp + u.Magnitude(ct_bkgsb)
+        else:
+            ct_bkgsb = 0. * u.ct / u.s
+            mag_bkgsb = 100. * u.mag
+        if mag_bkgsb.value < -100. :
+            mag_bkgsb = u.Quantity('100 mag')
+        if mag_bkgsb.value > 100.:
+            mag_bkgsb = u.Quantity('100 mag')
+
+        # Compute number of background electrons per pixel per second
+        # We explicitely assume that counts are per arcsec2
+        bkg_rate = (ct_bkgsb * gain * (
+            detector.scale[0].to(u.arcsec / u.pix)
+            * detector.scale[1].to(u.arcsec / u.pix)
+        )).value
+    else:
+        # Counts directly provided by user
+        bkg_rate = sky_photon_rate
+
+    # Instantiate image model
+    img = Image(
+        source=q.source,
+        psf_fwhm=q.seeing * u.arcsec,
+        psf_beta=3.2,
+        sersic_radius=q.sersic_radius,
+        sersic_index=q.sersic_index,
+        pixel=detector.scale,
+        rate=photon_rate,
+        bkg_rate=bkg_rate,
+        # Use RON 'counts' instead of electrons for compatibility with synphot
+        ron=detector.ron.to_value('electron'),
+        gain=gain,
+        photometry=q.photometry,
+        aperture=q.aperture
+    )
+
+    sexposures = sqrt(q.exposures * 2. / pi) if \
+        q.stacking == 'median' and q.exposures > 2 else sqrt(q.exposures)
+       
+    if q.compute == 'etime':
+        snr = q.snr / sexposures
+        # Compute exposure time (solution to a second degree equation) in s
+        etime = img.etime(snr)
+    else:
+        etime = q.etime
+        snr = img.snr(etime)
+
+    if ui:
+        full_wave, full_response = spectral_to_arrays(full_spec)
+        atmosphere_wave, atmosphere_response = spectral_to_arrays(atmosphere_spec)
+
+    return ETCResponseModel(
+            instrument = instrument.name,
+            filter = instrument_transmission.name,
+            compute = q.compute,
+            zp = zp.value,
+            snr = snr * sexposures,
+            etime = etime,
+            etime_skysat = img.etime_bkg_sat(),
+            etime_sourcesat = img.etime_source_sat(),
+            ttime = q.exposures * (etime + instrument.overhead.to_value(u.s)),
+            sky_mag = mag_bkgsb.value,
+            lambda_pivot = lambda_pivot.to_value(u.nm),
+            bandwidth_rect = dlambda_rect.to_value(u.nm),
+            cutout = img.gif(etime, exposures=q.exposures) if ui else None,
+            filter_transmission = TransmissionModel(
+                id = instrument_transmission.id,
+                name = instrument_transmission.name,
+                wave_range = instrument.wavelength_range,
+                wave = full_wave,
+                response = full_response
+            ).model_dump_json(
+                exclude={'spectral'}
+            ) if ui else None,
+            atmosphere_transmission =  TransmissionModel(
+                id = 'atmosphere',
+                name = "Atmosphere",
+                wave_range = instrument.wavelength_range,
+                wave = atmosphere_wave,
+                response = atmosphere_response
+            ).model_dump_json() if ui else None
+    )
+
+

pydiet/server/types/__init__.py

@@ -0,0 +1,8 @@
+"""
+Data types
+"""
+# Copyright CFHT/CNRS/CEA/UParisSaclay
+# Licensed under the MIT licence
+from .quantity import AnnotatedQuantity, str_to_quantity_array
+from .string import AnnotatedStr
+