metablate 0.1.0__tar.gz → 0.4.0__tar.gz

{metablate-0.1.0 → metablate-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metablate
-Version: 0.1.0
+Version: 0.4.0
 Summary: A collection of meteor ablation models
 Author-email: Daniel Kastinen <daniel.kastinen@irf.se>, Johan Kero <kero@irf.se>
 Maintainer-email: Daniel Kastinen <daniel.kastinen@irf.se>
@@ -694,12 +694,15 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: tqdm
 Requires-Dist: scipy
-Requires-Dist: numpy
+Requires-Dist: numpy>2
+Requires-Dist: numba>=0.60
 Requires-Dist: matplotlib
-Requires-Dist: xarray
 Requires-Dist: pymsis
+Requires-Dist: xarray
+Requires-Dist: spacecoords>0.2
 Provides-Extra: develop
 Requires-Dist: pytest; extra == "develop"
+Requires-Dist: mypy; extra == "develop"
 Requires-Dist: flake8; extra == "develop"
 Requires-Dist: wheel; extra == "develop"
 Requires-Dist: build; extra == "develop"
@@ -722,45 +725,100 @@ Requires-Dist: mkdocs-section-index; extra == "develop"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: mypy; extra == "tests"
+Provides-Extra: visualization
+Requires-Dist: pyvista; extra == "visualization"
 Dynamic: license-file
 
 # Meteoroid Ablation Models
 
+`metablate` provides meteoroid ablation and atmospheric-entry models, MSIS
+atmospheres, material presets, and plasma-density calculations.
+
 ## Install
 
+Install the latest published release:
+
 ```bash
-    pip install ablate
+pip install metablate
 ```
 
-### matplotlib backends
+The bleeding-edge version is available with:
 
-on arch to get matplotlib to work
+```bash
+pip install git+https://github.com/danielk333/ablate.git
+```
+
+or trough cloning this repo.
 
-`pip install Qt5Agg`
+## Minimal ablation example
 
-and add a `~/.config/matplotlib/matplotlibrc` with `backend:qt5agg`.
+Run the Kero–Szasz (2008) model with a cometary meteoroid and the default
+`AtmPymsis` atmosphere:
 
-see `https://matplotlib.org/stable/tutorials/introductory/usage.html#backends`
+```python
+import numpy as np
+from spacecoords import frames
 
-### msise00 atmospheric model
+import metablate.material as mat
+import metablate.models.kero_szasz_2008 as ks
 
-make sure cmake is installed! `sudo pacman -S cmake` and also gfortran `sudo pacman -S gcc gcc-fortran` and the basic libs `sudo pacman -S base-devel`
+lat, lon = 67.0, 20.0
+position = frames.geodetic_wgs84_to_ecef(lat, lon, 100e3, degrees=True)
+direction = frames.azel_to_ecef(lat, lon, az=10, el=-45, degrees=True)
+
+model = ks.KeroSzasz2008(
+    options=ks.KeroSzaszOptions(
+        material=mat.cometary,
+        atmosphere_kwargs=dict(as_dataset=False),
+    ),
+)
+result = model.run(
+    parameters=ks.KeroSzaszInitialState(
+        epoch=np.datetime64("2018-06-28T12:45:33"),
+        position_ecef=position,
+        velocity_ecef=direction * 60e3,
+        mass=1e-6,
+    ),
+)
+print(f"Runtime: {result.runtime:.3f} s")
+```
 
-if compilation fails use the enviormennt variables, for bash `export FC="/usr/bin/gfortran"` in fish `set -x FC "/usr/bin/gfortran"`. If cmake still tries to use gcc for compilation, make sure to remove the build folder under `my_env/lib/pythonX.X/site-packages/msise00/build` so that no cached files override the enviornment variables.
+Positions and velocities use ECEF coordinates in metres and metres per second;
+mass is in kilograms. Results include time, mass, velocity, temperature and position.
 
+## Atmospheres and computation
+
+`AtmPymsis` uses `pymsis`, with MSIS 2.1 by default. Historical solar and geomagnetic
+indices are downloaded and cached when not supplied. Setting `as_dataset=False`
+in `atmosphere_kwargs` avoids constructing an xarray dataset at each solver step.
+
+`AtmMSISE00` is optional and requires the separate `msise00` package and a Fortran
+compiler; see its [installation instructions](https://github.com/space-physics/msise00#install).
+
+Some functions use Numba to speed up subsequent calls. The first call
+compiles the kernels, which are cached for subsequent runs. Set `NUMBA_DISABLE_JIT=1`
+to run the same formulas in Python for debugging.
+
+## Examples
+
+See [docs/examples](docs/examples) for e.g. ablation, fireball, alpha–beta and plasma examples.
+For example, after a repository checkout, generate an ablation sweep with:
 
 ```bash
-    mkdir /my/env/msise00_source
-    cd /my/env/msise00_source
-    git clone https://github.com/scivision/msise00
-    cd msise00
-    pip install -e .
-    python -c "import msise00; msise00.base.build()"
+python docs/examples/ablation_sweep.py --output ablation_sweep.png
 ```
 
-or
+Which produces this plot:
+
+![Kero-Szasz ablation sweep](docs/assets/kero_figure1_example.png)
+
+## Development
+
+From a repository checkout:
 
 ```bash
-pip install git+git://github.com/space-physics/msise00.git@main
-python -c "import msise00; msise00.base.build()"
+pip install -e .[tests]
+# or pip install -e .[develop] for all dev packages
+pytest
 ```

metablate-0.4.0/README.md

@@ -0,0 +1,92 @@
+# Meteoroid Ablation Models
+
+`metablate` provides meteoroid ablation and atmospheric-entry models, MSIS
+atmospheres, material presets, and plasma-density calculations.
+
+## Install
+
+Install the latest published release:
+
+```bash
+pip install metablate
+```
+
+The bleeding-edge version is available with:
+
+```bash
+pip install git+https://github.com/danielk333/ablate.git
+```
+
+or trough cloning this repo.
+
+## Minimal ablation example
+
+Run the Kero–Szasz (2008) model with a cometary meteoroid and the default
+`AtmPymsis` atmosphere:
+
+```python
+import numpy as np
+from spacecoords import frames
+
+import metablate.material as mat
+import metablate.models.kero_szasz_2008 as ks
+
+lat, lon = 67.0, 20.0
+position = frames.geodetic_wgs84_to_ecef(lat, lon, 100e3, degrees=True)
+direction = frames.azel_to_ecef(lat, lon, az=10, el=-45, degrees=True)
+
+model = ks.KeroSzasz2008(
+    options=ks.KeroSzaszOptions(
+        material=mat.cometary,
+        atmosphere_kwargs=dict(as_dataset=False),
+    ),
+)
+result = model.run(
+    parameters=ks.KeroSzaszInitialState(
+        epoch=np.datetime64("2018-06-28T12:45:33"),
+        position_ecef=position,
+        velocity_ecef=direction * 60e3,
+        mass=1e-6,
+    ),
+)
+print(f"Runtime: {result.runtime:.3f} s")
+```
+
+Positions and velocities use ECEF coordinates in metres and metres per second;
+mass is in kilograms. Results include time, mass, velocity, temperature and position.
+
+## Atmospheres and computation
+
+`AtmPymsis` uses `pymsis`, with MSIS 2.1 by default. Historical solar and geomagnetic
+indices are downloaded and cached when not supplied. Setting `as_dataset=False`
+in `atmosphere_kwargs` avoids constructing an xarray dataset at each solver step.
+
+`AtmMSISE00` is optional and requires the separate `msise00` package and a Fortran
+compiler; see its [installation instructions](https://github.com/space-physics/msise00#install).
+
+Some functions use Numba to speed up subsequent calls. The first call
+compiles the kernels, which are cached for subsequent runs. Set `NUMBA_DISABLE_JIT=1`
+to run the same formulas in Python for debugging.
+
+## Examples
+
+See [docs/examples](docs/examples) for e.g. ablation, fireball, alpha–beta and plasma examples.
+For example, after a repository checkout, generate an ablation sweep with:
+
+```bash
+python docs/examples/ablation_sweep.py --output ablation_sweep.png
+```
+
+Which produces this plot:
+
+![Kero-Szasz ablation sweep](docs/assets/kero_figure1_example.png)
+
+## Development
+
+From a repository checkout:
+
+```bash
+pip install -e .[tests]
+# or pip install -e .[develop] for all dev packages
+pytest
+```

{metablate-0.1.0 → metablate-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "metablate"
-version = "0.1.0"
+version = "0.4.0"
 description = "A collection of meteor ablation models"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [
@@ -27,10 +27,12 @@ requires-python = ">=3.9"
 dependencies = [
     "tqdm",
     "scipy",
-    "numpy",
+    "numpy>2",
+    "numba>=0.60",
     "matplotlib",
-    "xarray",
     "pymsis",
+    "xarray",
+    "spacecoords>0.2",
 ]
 
 [tool.setuptools]
@@ -43,6 +45,7 @@ where = ["src"]
 [project.optional-dependencies]
 develop = [
     "pytest",
+    "mypy",
     "flake8",
     "wheel",
     "build",
@@ -63,7 +66,8 @@ develop = [
     "mkdocs-literate-nav",
     "mkdocs-section-index",
 ]
-tests = ["pytest", "pytest-cov"]
+tests = ["pytest", "pytest-cov", "mypy"]
+visualization = ["pyvista"]
 
 
 [project.urls]
@@ -74,3 +78,25 @@ Issues = "https://github.com/danielk333/ablate/issues"
 
 [tool.black]
 line-length = 100
+
+[tool.mypy]
+disallow_untyped_defs = true
+follow_untyped_imports = true
+warn_unused_ignores = true
+packages = ["metablate"]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.ruff.lint]
+ignore = ["E203","D203","E251","E501","E226"]
+
+[tool.pytest]
+addopts = ["-v", "--cov=metablate"]
+testpaths = ["tests"]
+markers = [
+    "slow: tests expected to take longer than simple unit checks",
+]

metablate-0.4.0/src/metablate/__init__.py

@@ -0,0 +1,25 @@
+"""
+# Meteoroid Ablation Models
+"""
+from __future__ import annotations
+
+import logging
+import sys
+
+from . import atmosphere, material, models, physics
+from .atmosphere import Atmosphere
+from .version import __version__
+
+
+def setup_logging(level: int | str = logging.INFO) -> logging.Logger:
+    logger = logging.getLogger("metablate")
+    logger.setLevel(level)
+
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(level)
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+    return logger

{metablate-0.1.0 → metablate-0.4.0}/src/metablate/atmosphere/atm_msise00.py

@@ -1,36 +1,45 @@
-#!/usr/bin/env python
-
 """msis00
 
 """
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+import numpy as np
 import scipy.constants
+import xarray as xr
+
+from ..types import ArrayLike
 from .atmosphere import Atmosphere
-import numpy.typing as npt
 
+msise00: ModuleType | None
 try:
-    import msise00
+    msise00 = import_module("msise00")
 except ImportError:
     msise00 = None
 
 
 class AtmMSISE00(Atmosphere):
-    def __init__(self):
+
+    def __init__(self) -> None:
         super().__init__(
             supported_species=["He", "O", "N2", "O2", "Ar", "H", "N"],
         )
 
     def density(
         self,
-        time: npt.ArrayLike,
-        lat: npt.ArrayLike,
-        lon: npt.ArrayLike,
-        alt: npt.ArrayLike,
+        time: ArrayLike,
+        lat: ArrayLike,
+        lon: ArrayLike,
+        alt: ArrayLike,
         f107: float = 80.0,
         f107s: float = 80.0,
         Ap: float = 4.0,
         mass_densities: bool = False,
-        **kwargs
-    ):
+        **kwargs: Any,
+    ) -> xr.Dataset:
         """TODO: Write docstring
 
         returns density in [m^-3]
@@ -41,7 +50,7 @@ class AtmMSISE00(Atmosphere):
 
         result = msise00.run(
             time=time,
-            altkm=alt * 1e-3,
+            altkm=np.asarray(alt) * 1e-3,
             glat=lat,
             glon=lon,
             indices=dict(
@@ -49,7 +58,7 @@ class AtmMSISE00(Atmosphere):
                 f107s=f107s,
                 Ap=Ap,
             ),
-            **kwargs
+            **kwargs,
         )
         result["alt_km"] = result["alt_km"]*1e3
         result = result.rename({

metablate-0.4.0/src/metablate/atmosphere/atm_pymsis.py

@@ -0,0 +1,126 @@
+"""pymsis
+
+"""
+from __future__ import annotations
+
+from types import ModuleType
+from typing import Any
+
+import numpy as np
+import scipy.constants
+import xarray as xr
+
+from ..types import ArrayLike, AtmosphereData
+from .atmosphere import Atmosphere
+
+msis: ModuleType | None
+try:
+    from pymsis import msis
+except ImportError:
+    msis = None
+
+
+class AtmPymsis(Atmosphere):
+    """
+    # TODO: docstring
+
+    ndarray (ndates, nlons, nlats, nalts, 11) or (ndates, 11) | 
+    The data calculated at each grid point: 
+    | [Total mass density (kg/m3) | N2 # density (m-3), | O2 # density (m-3), | 
+    O # density (m-3), | He # density (m-3), | H # density (m-3), | 
+    Ar # density (m-3), | N # density (m-3), | 
+    Anomalous oxygen # density (m-3), | NO # density (m-3), 
+    | Temperature (K)]
+    """
+    def __init__(self) -> None:
+        super().__init__(
+            supported_species=["He", "O", "N2", "O2", "Ar", "H", "N"],
+        )
+
+    def density(
+        self,
+        time: ArrayLike,
+        lat: ArrayLike,
+        lon: ArrayLike,
+        alt: ArrayLike,
+        f107: ArrayLike | None = None,
+        f107s: ArrayLike | None = None,
+        aps: ArrayLike | None = None,
+        mass_densities: bool = False,
+        version: float | str = 2.1,
+        as_dataset: bool = True,
+        **kwargs: Any,
+    ) -> AtmosphereData:
+        """Return species number densities [m^-3], or mass densities [kg/m^3].
+
+        Set ``as_dataset=False`` in an ablation model's ``atmosphere_kwargs``
+        to skip dataset and coordinate construction at each solver step.
+        The returned variables still support ``.values``; total mass density
+        and temperature retain their units of kg/m^3 and K, respectively.
+        """
+        if msis is None:
+            raise ImportError("pymsis is not installed")
+
+        time = np.array(time) if not isinstance(time, np.ndarray) else time
+        lon = np.array(lon) if not isinstance(lon, np.ndarray) else lon
+        lat = np.array(lat) if not isinstance(lat, np.ndarray) else lat
+        alt = np.array(alt) if not isinstance(alt, np.ndarray) else alt
+
+        for inp in [time, lon, lat, alt]:
+            if len(inp.shape) == 0:
+                inp.shape = (1,)
+
+        data = msis.run(
+            dates=time,
+            lons=lon,
+            lats=lat,
+            alts=alt * 1e-3,
+            f107s=f107,
+            f107as=f107s,
+            aps=aps,
+            version=version,
+            **kwargs,
+        )
+        if len(data.shape) == 2:
+            data = data.reshape(data.shape[0], 1, 1, 1, data.shape[1])
+
+        variables = {
+            "Total": (["time", "lon", "lat", "alt"], data[:, :, :, :, 0]),
+            "N2": (["time", "lon", "lat", "alt"], data[:, :, :, :, 1]),
+            "O2": (["time", "lon", "lat", "alt"], data[:, :, :, :, 2]),
+            "O": (["time", "lon", "lat", "alt"], data[:, :, :, :, 3]),
+            "He": (["time", "lon", "lat", "alt"], data[:, :, :, :, 4]),
+            "H": (["time", "lon", "lat", "alt"], data[:, :, :, :, 5]),
+            "Ar": (["time", "lon", "lat", "alt"], data[:, :, :, :, 6]),
+            "N": (["time", "lon", "lat", "alt"], data[:, :, :, :, 7]),
+            "AnomalousO": (["time", "lon", "lat", "alt"], data[:, :, :, :, 8]),
+            "NO": (["time", "lon", "lat", "alt"], data[:, :, :, :, 9]),
+            "Temperature": (["time", "lon", "lat", "alt"], data[:, :, :, :, 10]),
+        }
+        result: AtmosphereData
+        if as_dataset:
+            result = xr.Dataset(
+                variables,
+                coords={
+                    "time": time,
+                    "lon": lon,
+                    "lat": lat,
+                    "alt": alt,
+                },
+                attrs=dict(
+                    f107=f107,
+                    f107s=f107s,
+                    aps=aps,
+                    mass_densities=mass_densities,
+                    version=version,
+                ),
+            )
+        else:
+            result = {key: xr.Variable(*value) for key, value in variables.items()}
+
+        if mass_densities:
+            for symbol, s in self.species.items():
+                weight = scipy.constants.u * s.A
+                result[symbol] = result[symbol] * weight
+
+        return result

{metablate-0.1.0 → metablate-0.4.0}/src/metablate/atmosphere/atmosphere.py

@@ -1,11 +1,15 @@
-from abc import abstractmethod
-from dataclasses import dataclass
+from __future__ import annotations
+
 import logging
+from abc import abstractmethod
 from copy import copy
+from dataclasses import dataclass
+from typing import Any
 
-import scipy.constants as constants
 import numpy as np
-import numpy.typing as npt
+from scipy import constants
+
+from ..types import ArrayLike, AtmosphereData
 
 logger = logging.getLogger(__name__)
 
@@ -58,7 +62,8 @@ SPECIES = {
 
 # TODO: get a a hold of other atm models to figure out how to generalize interface better
 class Atmosphere:
-    def __init__(self, supported_species):
+
+    def __init__(self, supported_species: list[Species] | list[str]) -> None:
         self.species = {}
         for s in supported_species:
             if isinstance(s, Species):
@@ -70,11 +75,6 @@ class Atmosphere:
 
     @abstractmethod
     def density(
-        self,
-        time: npt.ArrayLike,
-        lat: npt.ArrayLike,
-        lon: npt.ArrayLike,
-        alt: npt.ArrayLike,
-        **kwargs
-    ):
+        self, time: ArrayLike, lat: ArrayLike, lon: ArrayLike, alt: ArrayLike, **kwargs: Any
+    ) -> AtmosphereData:
         pass