Merge pull request #29 from Cosmoglobe/v1.0.0

v1.0.0 looks awesome

.github/workflows/draft-pdf.yml

@@ -1,4 +1,9 @@
-on: [push, workflow_dispatch]
+on:
+  push:
+    paths: ["paper/**"]
+  pull_request:
+    paths: ["paper/**"]
+  workflow_dispatch:
 
 jobs:
   paper:
@@ -20,4 +25,4 @@ jobs:
           # This is the output path where Pandoc will write the compiled
           # PDF. Note, this should be the same directory as the input
           # paper.md
-          path: paper/paper.pdf
+          path: paper/paper.pdf

.gitignore

@@ -173,4 +173,7 @@ settings.json
 test.py
 context.py
 
-*.pdf
+*.pdf
+
+work_in_progress/
+old_tests/

.pre-commit-config.yaml

@@ -2,17 +2,44 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.3.0
     hooks:
-    - id: check-added-large-files
-    - id: check-yaml
-      langauge_version: python3
+      - id: check-added-large-files
+      - id: check-yaml
+        langauge_version: python3
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
     rev: v0.3.7
     hooks:
       - id: ruff
       - id: ruff-format
 
-hooks:
-  - id: poetry-export
-    args: ["--dev", "-f", "requirements.txt", "-o", "requirements-dev.txt"]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        exclude: "(tests|docs)/.*"
+        additional_dependencies: [numpy>=1.21.0]
+
+  - repo: local
+    hooks:
+      - id: poetry-check
+        name: poetry-check
+        description: run poetry check to validate config
+        entry: poetry check
+        language: python
+        pass_filenames: false
+        files: ^(.*/)?pyproject\.toml$
+      - id: poetry-lock
+        name: poetry-lock
+        description: run poetry lock to update lock file
+        entry: poetry lock
+        language: python
+        pass_filenames: false
+        files: ^(.*/)?(poetry\.lock|pyproject\.toml)$
+      - id: poetry-export
+        name: poetry-export
+        description: run poetry export to sync lock file with requirements-dev.txt
+        entry: poetry export
+        language: python
+        pass_filenames: false
+        files: ^(.*/)?poetry\.lock$
+        args: ["-f", "requirements.txt", "-o", "requirements.txt"]

README.md

@@ -16,33 +16,38 @@
 ---
 
 
+
 ZodiPy is an [Astropy affiliated](https://www.astropy.org/affiliated/#affiliated-package-list) package for simulating zodiacal light in intensity for arbitrary Solar system observers.
 
 ![plot](docs/img/zodipy_map.png)
 
+
 ## Documentation
-See the [documentation](https://cosmoglobe.github.io/zodipy/) for more information and examples on how to use ZodiPy for different applications.
+See the [documentation](https://cosmoglobe.github.io/zodipy/) for a list of supported zodiacal light models and examples of how to use ZodiPy.
 
 ## A simple example
 ```python
 import astropy.units as u
+from astropy.coordinates import SkyCoord
 from astropy.time import Time
 
-from zodipy import Zodipy
+import zodipy
 
+# Initialize a zodiacal light model at a wavelength/frequency or over a bandpass
+model = zodipy.Model(25*u.micron)
 
-model = Zodipy(model="dirbe")
+# Use Astropy's `SkyCoord` to specify coordinate
+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"])
 
-emission = model.get_emission_ang(
-    25 * u.micron,
-    theta=[10, 10.1, 10.2] * u.deg,
-    phi=[90, 89, 88] * u.deg,
-    obs_time=Time("2022-01-01 12:00:00"),
-    obs="earth",
-)
+skycoord = SkyCoord(lon, lat, obstime=obstimes, frame="galactic")
+
+# Compute the zodiacal light as seen from Earth
+emission = model.evaluate(skycoord, obspos="earth")
 
 print(emission)
-#> [15.35392831 15.35495051 15.35616009] MJy / sr
+#> [27.52410841 27.66572294 27.81251906] MJy / sr
 ```
 
 ## Related scientific papers
@@ -52,63 +57,55 @@ See [CITATION](https://github.com/Cosmoglobe/zodipy/blob/main/CITATION.bib)
 
 
 ## Install
-ZodiPy is installed using `pip install zodipy`.
+ZodiPy is installed with pip
+```bash
+pip install zodipy
+```
 
 ## Dependencies
 ZodiPy supports all Python versions >= 3.9, and has the following dependencies:
 - [Astropy](https://www.astropy.org/) (>=5.0.1)
 - [NumPy](https://numpy.org/)
-- [healpy](https://healpy.readthedocs.io/en/latest/)
 - [jplephem](https://pypi.org/project/jplephem/)
 - [SciPy](https://scipy.org/)
 
 ## For developers
-Contributing developers will need to download the following additional dependencies to test, lint, format and build documentation locally:
-- pytest
-- pytest-cov
-- hypothesis
-- coverage
-- ruff
-- mypy
-- pre-commit
-- mkdocs
-- pymdown-extensions
-- markdown-include
-- mkdocs-material
-- mkdocstrings
-- mkdocstrings-python
-- markdown (<3.4.0)
-
-which are required to test and build ZodiPy.
-
 ### Poetry
-Developers can install ZodiPy through [Poetry](https://python-poetry.org/) (Poetry >= 1.8.0) by first cloning or forking the repository, and then running 
-```
-poetry install
-```
-in a virtual environment from the repository root. This will read the `pyproject.toml` file in the repository and install all dependencies. 
+ZodiPy uses [Poetry](https://python-poetry.org/) for development. To build and commit to the repository with the existing pre-commit setup, developers need to have Poetry (>= 1.8.0) installed. See the Poetry [documentation](https://python-poetry.org/docs/) for installation guide. 
 
-### pip
-Developers not using Poetry can install ZodiPy in a virtual environment with all dependencies by first cloning or forking the repository and then running 
+After poetry has been installed, developers should create a new virtual environment and run the following in the root of the ZodiPy repositry
 ```
-pip install -r requirements-dev.txt
+poetry install
 ```
-from the repositry root. This will read and download all the dependencies from the `requirements-dev.txt` file in the repository. 
+This will download all dependencies (including dev)from `pyproject.toml`, and `poetry.lock`.
 
-Note that developers using Python 3.12 will need to upgrade their pip versions with `python3 -m pip install --upgrade pip` before being able to install ZodiPy. This is due to known incompatibilities between older pip versions and Python 3.12
-
-### Tests, linting and formatting
+### Tests, linting and formatting, and building documentation
 The following tools should be run from the root of the repository with no errors. (These are ran automatically as part of the CI workflows on GitHub, but should be tested locally first)
 
-- [pytest](https://docs.pytest.org/en/8.0.x/): Tests are run with pytest by simply running `pytest` in the command line in the root of the repository. 
-- [ruff](https://github.com/astral-sh/ruff): Formating and linting is done with `ruff` by simply running `ruff check` and `ruff format` in the command line in the root of the repository. 
-- [mypy](https://mypy-lang.org/): Type checking is done with `mypy` by simply running `mypy zodipy/` in the root of the repository.
-
+#### pytest
+Testing is done with [pytest](https://docs.pytest.org/en/8.0.x/). To run the tests, run the following command from the repository root
+```bash
+pytest
+``` 
+#### ruff
+Formating and linting is done with [ruff](https://github.com/astral-sh/ruff). To format and lint, run the following command from the repository root
+```bash
+ruff check
+ruff format
+``` 
+#### mypy
+ZodiPy is fully typed. We use [mypy](https://mypy-lang.org/) as a static type checker. To type check, run the following command from the repositry root
+
+```bash
+mypy zodipy/
+```
 Remeber to add tests when implementing new features to maintain a high code coverage.
 
-### Documentation
-We use [MkDocs](https://www.mkdocs.org/) to create our documentation. The documentation is built locally with `mkdocs build` from the repository root, and served with `mkdocs serve`.
-
+#### MkDocs
+We use [MkDocs](https://www.mkdocs.org/) to create our documentation. To serve the docs locally on you machine, run the following from the repositry root
+```bash
+mkdocs serve
+```
 
 ## Funding
 This work has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreements No 776282 (COMPET-4; BeyondPlanck), 772253 (ERC; bits2cosmology) and 819478 (ERC; Cosmoglobe).

docs/examples/astropy_healpix_map.py

@@ -0,0 +1,33 @@
+import multiprocessing
+
+import astropy.units as u
+import astropy_healpix as ahp
+import healpy as hp
+import matplotlib.pyplot as plt
+import numpy as np
+from astropy.time import Time
+
+import zodipy
+
+model = zodipy.Model(30 * u.micron)
+
+healpix = ahp.HEALPix(nside=256, frame="galactic")
+pixels = np.arange(healpix.npix)
+skycoord = healpix.healpix_to_skycoord(pixels)
+
+# Note that we manually set the obstime attribute
+skycoord.obstime = Time("2022-01-14")
+
+emission = model.evaluate(skycoord, nprocesses=multiprocessing.cpu_count())
+
+# Plot with healpy
+hp.mollview(
+    emission,
+    unit="MJy/sr",
+    cmap="afmhot",
+    min=0,
+    max=80,
+    title="Zodiacal light at 30 µm (2022-01-14)",
+)
+# plt.savefig("../img/healpix_map.png", dpi=300, bbox_inches="tight")
+plt.show()

docs/examples/component_maps.py

@@ -0,0 +1,49 @@
+import multiprocessing
+
+import astropy.units as u
+import healpy as hp
+import matplotlib.pyplot as plt
+import numpy as np
+from astropy.coordinates import SkyCoord
+from astropy.time import Time
+
+import zodipy
+
+COMP_NAMES = [
+    "Smooth cloud",
+    "Dust band 1",
+    "Dust band 2",
+    "Dust band 3",
+    "Circum-solar Ring",
+    "Earth-trailing Feature",
+]
+
+model = zodipy.Model(24 * u.micron)
+
+nside = 128
+pixels = np.arange(hp.nside2npix(nside))
+lon, lat = hp.pix2ang(nside, pixels, lonlat=True)
+
+skycoord = SkyCoord(
+    lon,
+    lat,
+    unit=u.deg,
+    frame="barycentricmeanecliptic",
+    obstime=Time("2022-01-14"),
+)
+
+emission = model.evaluate(skycoord, return_comps=True, nprocesses=multiprocessing.cpu_count())
+
+fig = plt.figure(figsize=(8, 7))
+for idx, comp_emission in enumerate(emission):
+    hp.mollview(
+        comp_emission,
+        title=COMP_NAMES[idx],
+        norm="log" if idx == 0 else None,
+        cmap="afmhot",
+        cbar=False,
+        sub=(3, 2, idx + 1),
+        fig=fig,
+    )
+plt.savefig("../img/component_maps.png", dpi=250, bbox_inches="tight")
+plt.show()

docs/examples/ecliptic_scan.py

@@ -0,0 +1,28 @@
+import astropy.units as u
+import matplotlib.pyplot as plt
+import numpy as np
+from astropy.coordinates import BarycentricMeanEcliptic, SkyCoord
+from astropy.time import Time
+
+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)
+
+coords = SkyCoord(
+    lons,
+    lats,
+    frame=BarycentricMeanEcliptic,
+    obstime=Time("2022-06-14"),
+)
+
+emission = model.evaluate(coords)
+
+plt.plot(lats, emission)
+plt.xlabel("Latitude [deg]")
+plt.ylabel("Emission [MJy/sr]")
+plt.savefig("../img/ecliptic_scan.png", dpi=300, bbox_inches="tight")
+plt.show()