Update docs

docs/examples/ecliptic_scan.py

@@ -2,21 +2,24 @@
 import matplotlib.pyplot as plt
 import numpy as np
 from astropy.coordinates import BarycentricMeanEcliptic, SkyCoord
-from astropy.time import Time
+from astropy.time import Time, TimeDelta
 
 from zodipy import Model
 
 model = Model(30 * u.micron)
 
-# Longitude and Latitude values corresponding to a scan through the eclitpic plane
 lats = np.linspace(-90, 90, 100) * u.deg
 lons = np.zeros_like(lats)
 
+t0 = Time("2022-06-14")
+dt = TimeDelta(1, format="sec")
+obstimes = t0 + np.arange(lats.size) * dt
+
 coords = SkyCoord(
     lons,
     lats,
     frame=BarycentricMeanEcliptic,
-    obstime=Time("2022-06-14"),
+    obstime=obstimes,
 )
 
 emission = model.evaluate(coords)

docs/index.md

@@ -14,7 +14,8 @@
 [![DOI](https://zenodo.org/badge/394929213.svg)](https://zenodo.org/doi/10.5281/zenodo.10999611)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.06648/status.svg)](https://doi.org/10.21105/joss.06648)
 
-ZodiPy is an [Astropy-affiliated](https://www.astropy.org/affiliated/) package for simulating zodiacal light in intensity for arbitrary Solar system observers.
+ZodiPy is an [Astropy-affiliated](https://www.astropy.org/affiliated/) package for simulating 
+zodiacal light in intensity for arbitrary solar system observers.
 ![ZodiPy Logo](img/zodipy_map.png)
 
 ## A simple example
@@ -28,18 +29,17 @@ import zodipy
 # Initialize a zodiacal light model at a wavelength/frequency or over a bandpass
 model = zodipy.Model(25*u.micron)
 
-# Use Astropy's `SkyCoord` to specify coordinate
+# Use Astropy's `SkyCoord` object to specify coordinates
 lon = [10, 10.1, 10.2] * u.deg
 lat = [90, 89, 88] * u.deg
 obstimes = Time(["2022-01-01 12:00:00", "2022-01-01 12:01:00", "2022-01-01 12:02:00"])
-
 skycoord = SkyCoord(lon, lat, obstime=obstimes, frame="galactic")
 
-# Compute the zodiacal light as seen from Earth
-emission = model.evaluate(skycoord, obspos="earth")
+# Evaluate the zodiacal light model
+emission = model.evaluate(skycoord)
 
 print(emission)
 #> [27.52410841 27.66572294 27.81251906] MJy / sr
 ```
 
-For more information on using ZodiPy, see [the usage section](usage.md).
+For more information on using ZodiPy, see the [usage section](usage.md).

docs/install.md

@@ -10,7 +10,7 @@ pip install zodipy
 
 
 ## Dependencies
-ZodiPy has the following dependencies:
+ZodiPy has the following dependencies (these are automatically downloaded when using pip):
 
 - [Astropy](https://www.astropy.org) (>= 5.0.1)
 - [NumPy](https://numpy.org)

docs/introduction.md

@@ -1,8 +1,12 @@
 # Introduction
 
-ZodiPy is a Python package for zodiacal light simulations. Its purpose is to provide the astrophysics and cosmology communities with an easy-to-use and accessible interface to existing zodiacal light models in Python, assisting in astrophysical data analysis and zodiacal light forecasting for future experiments.
+ZodiPy is a Python package for zodiacal light simulations. Its purpose is to provide the 
+astrophysics and cosmology communities with an easy-to-use and accessible interface to existing 
+zodiacal light models in Python, assisting in astrophysical data analysis and zodiacal light 
+forecasting for future experiments.
 
-For other zodiacal light tools, see [Zodiacal Light Models on LAMBDA](https://lambda.gsfc.nasa.gov/product/foreground/fg_models.html).
+For other zodiacal light tools, see 
+[Zodiacal Light Models on LAMBDA](https://lambda.gsfc.nasa.gov/product/foreground/fg_models.html).
 
 ## Supported zodiacal light models
 
@@ -13,9 +17,11 @@ For other zodiacal light tools, see [Zodiacal Light Models on LAMBDA](https://la
 - Planck 2018 [`"planck18"`] ([Planck Collaboration et al. 2020](https://ui.adsabs.harvard.edu/abs/2020A&A...641A...3P))
 - Odegard [`"odegard"`] ([Odegard et al. 2019](https://ui.adsabs.harvard.edu/abs/2019ApJ...877...40O/abstract))
 
-The names in the brackets are the string representations used in the `zodipy.Model` object to select the model.
+The names in the brackets are the string representations used in the [`Model`][zodipy.Model] object 
+to select the model.
 
-If you see a missing model or wish to add a new one, please open an issue on GitHub. Contributors are very welcome!
+If you see a missing model or wish to add a new one, please feel free to open an issue on GitHub. 
+Contributors are very welcome!
 
 
 ## Related scientific papers

docs/reference.md

@@ -1,3 +1,3 @@
 # Reference
 
-::: zodipy.Model
+::: zodipy

zodipy/model.py

@@ -35,33 +35,35 @@ class Model:
 
     def __init__(
         self,
-        x: units.Quantity,
+        x: units.Quantity[units.micron | units.GHz],
         *,
         weights: npt.ArrayLike | None = None,
         name: str = "dirbe",
         gauss_quad_degree: int = 50,
         extrapolate: bool = False,
         ephemeris: str = "builtin",
     ) -> None:
-        """Initialize the ZodiPy model interface.
+        """Initialize a zodiacal light model.
 
         Args:
-            x: Wavelength or frequency. If `x` is a sequence, it is assumed to be a the points
-                corresponding to a bandpass and the corresponding `weights` must be provided.
-            weights: Bandpass weights corresponding the the frequencies or wavelengths in `x`. The
+            x: Wavelength or frequency. If `x` is a sequence it is assumed to be a the points
+                corresponding to an instrument bandpass and the corresponding `weights` argument
+                must be provided.
+            weights: Bandpass weights corresponding the the frequencies/wavelengths in `x`. The
                 weights are assumed to represent a normalized instrument response in units of
-                spectral radiance (Jy/sr).
-            name: Zodiacal light model to use for the simulations. For a list of available models,
-                see https://cosmoglobe.github.io/zodipy/introduction/. Defaults to 'dirbe'.
-            gauss_quad_degree: Order of the Gaussian-legendre quadrature used to evaluate the
-                line-of-sight integrals in the simulations. Default is 50 points.
+                spectral radiance [Jy/sr].
+            name: Zodiacal light model to use. See the
+                [docs](https://cosmoglobe.github.io/zodipy/introduction/) for list of available
+                models. Defaults to 'dirbe'.
+            gauss_quad_degree: Order of the Gaussian-legendre quadrature representing the number of
+                discrete points along each line-of-sight. Default is 50 points.
             extrapolate: If `True` all spectral quantities in the selected model are extrapolated to
-                the requested frequencies or wavelengths. If `False`, an exception is raised on
-                requested values of `x` outside of the valid model range. Default is `False`.
-            ephemeris: Ephemeris used in `astropy.coordinates.solar_system_ephemeris` to compute the
-                positions of the observer and Earth. Defaults to 'builtin'. See the
+                the requested frequencies/wavelengths. Else, an exception is raised on values of `x`
+                outside of the valid model range. Default is `False`.
+            ephemeris: Ephemeris used in Astropy's `solar_system_ephemeris` to compute the positions
+                of Earth and optionally the observer. See the
                 [Astropy documentation](https://docs.astropy.org/en/stable/coordinates/solarsystem.html)
-                for available ephemerides.
+                for all available ephemerides. Defaults to 'builtin'.
 
         """
         try:
@@ -118,34 +120,35 @@ def evaluate(
         self,
         skycoord: coords.SkyCoord,
         *,
-        obspos: units.Quantity | str = "earth",
+        obspos: units.Quantity[units.AU] | str = "earth",
         return_comps: bool = False,
         nprocesses: int = 1,
     ) -> units.Quantity[units.MJy / units.sr]:
         """Return the simulated zodiacal light.
 
-        The zodiacal light is simulated for a single, or a sequence of observations. If a single
-        `obspos` and `obstime` is provided for multiple coordinates, all coordinates are assumed to
-        be observed from that position at that time. Otherwise, each coordinate is simulated from
-        the corresponding observer position and time.
+        The zodiacal light is simulated for all sky coordinates present in the `skycoord` argument.
+        If an obstime and obspos value is not provided for each coordinate value, all coordinates
+        are assumed to be observed at an instant from the same position.
 
         Args:
-            skycoord: `astropy.coordinates.SkyCoord` object representing the coordinates or
-                observations for which to simulate the zodiacal light. The `frame` and `obstime`
-                attributes of the `SkyCoord` object must be set. The `obstime` attribute must be
-                specified, and correspond to a single, or a sequence of observational times with
-                length matching the number of coordinates. The frame must be convertible to the
+            skycoord: `astropy.coordinates.SkyCoord` object representing the coordinates for which
+                to simulate the zodiacal light. The `obstime` attribute must be specified, and
+                correspond to a either a single, or a sequence of observational times, one for each
+                coordinate in `skycoord`. The coordinate frame, provided through the `frame` keyword
+                in the the `astropy.coordinates.SkyCoord` object (defaults to
+                `astropy.coordinates.ICRS`), must be convertible to the
                 `astropy.coordinates.BarycentricMeanEcliptic` frame.
-            obspos: The heliocentric ecliptic position of the observer, or a string representing
-                an observer in the `astropy.coordinates.solar_system_ephemeris`. If an explicit
-                position is given, it must either be a single, or a sequence of positions with
-                shape matching the number of coordinates Defaults to 'earth'.
-            return_comps: If True, the emission is returned component-wise. Defaults to False.
+            obspos: The heliocentric ecliptic position of the observer, or a string representing an
+                observer supported by the `astropy.coordinates.solar_system_ephemeris`. If an
+                explicit position is given, it must either be a single, or a sequence of positions,
+                one for each coordinate. Defaults to 'earth'.
+            return_comps: If `True`, the emission is returned component-wise. Defaults to `False`.
             nprocesses: Number of cores to use. If `nprocesses >= 1`, the line-of-sight integrals
-                are parallelized using the `multiprocessing` module. Defaults to 1.
+                are distributed and computed in parallel using the `multiprocessing` module.
+                Defaults to 1.
 
         Returns:
-            emission: Simulated zodiacal light in units of 'MJy/sr'.
+            emission: Simulated zodiacal light [MJy/sr].
 
         """
         try:
@@ -296,25 +299,22 @@ def _init_ipd_model_partials(self) -> None:
         self._number_density_partials = get_partial_number_density_func(comps=self._ipd_model.comps)
 
     def get_parameters(self) -> dict:
-        """Return a dictionary containing the interplanetary dust model parameters.
-
-        This method is mainly meant to be used to fit or sample zodiacal light models.
+        """Return a dictionary containing the zodiacal light model parameters.
 
         Returns:
-            parameters: Dictionary of parameters of the interplanetary dust model.
+            parameters: Zodiacal light model parameter dict.
         """
         return self._ipd_model.to_dict()
 
     def update_parameters(self, parameters: dict) -> None:
-        """Update the interplanetary dust model parameters.
+        """Update the zodiacal light model parameters from a parameter dictionary.
 
-        This method is mainly meant to be used to fit or sample zodiacal light models.
+        The structure of the input dictionary must match that of the output of the `get_parameters`
+        method.
 
         Args:
-            parameters: Dictionary of parameters to update. The keys must be the names
-                of the parameters as defined in the model. To get the parameters dict
-                of an existing model, use the`get_parameters` method of an initialized
-                `zodipy.Model`.
+            parameters: Zodiacal light model parameter dict.
+
         """
         _dict = parameters.copy()
         _dict["comps"] = {}

zodipy/number_density.py

@@ -479,21 +479,21 @@ def update_partial_earth_pos(
 
 
 def grid_number_density(
-    x: units.Quantity,
-    y: units.Quantity,
-    z: units.Quantity,
+    x: units.Quantity[units.AU],
+    y: units.Quantity[units.AU],
+    z: units.Quantity[units.AU],
     obstime: time.Time,
-    name: str = "DIRBE",
+    name: str = "dirbe",
     ephemeris: str = "builtin",
 ) -> npt.NDArray[np.float64]:
-    """Return the tabulated densities of the zodiacal components for a given grid.
+    """Return the component-wise tabulated densities of the zodiacal components for a given grid.
 
     Args:
-        x: Cartesian mesh grid x-coordinates.
-        y: Cartesian mesh grid y-coordinates.
-        z: Cartesian mesh grid z-coordinates.
-        obstime: Time of observation.
-        name: Interplanetary dust model to select. Default is 'DIRBE'.
+        x: x-coordinates of a cartesian mesh grid.
+        y: y-coordinates of a cartesian mesh grid.
+        z: z-coordinates of a cartesian mesh grid.
+        obstime: Time of observation. Required to compute the Earth position.
+        name: Zodiacal light model to use. Default is 'dirbe'.
         ephemeris: Solar system ephemeris to use. Default is 'builtin'.
 
     Returns:
@@ -505,7 +505,6 @@ def grid_number_density(
     grid = np.asarray(np.meshgrid(x, y, z))
 
     earthpos_xyz = get_earthpos_inst(obstime, ephemeris=ephemeris)
-    # Prepare attributes and variables for broadcasting with the grid
 
     # broadcasting reshapes
     for comp in ipd_model.comps.values():