metablate 0.1.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metablate
-Version: 0.1.0
+Version: 0.3.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,10 +694,12 @@ 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: flake8; extra == "develop"
@@ -722,45 +724,99 @@ Requires-Dist: mkdocs-section-index; extra == "develop"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; 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.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "metablate"
-version = "0.1.0"
+version = "0.3.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]
@@ -64,6 +66,7 @@ develop = [
     "mkdocs-section-index",
 ]
 tests = ["pytest", "pytest-cov"]
+visualization = ["pyvista"]
 
 
 [project.urls]
@@ -74,3 +77,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.3.0/src/metablate/__init__.py

@@ -0,0 +1,27 @@
+"""
+# Meteoroid Ablation Models
+"""
+
+import logging
+import sys
+
+from . import physics
+from . import models
+from . import material
+from . import atmosphere
+from .atmosphere import Atmosphere
+from .version import __version__
+
+
+def setup_logging(level=logging.INFO):
+    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.3.0}/src/metablate/atmosphere/atm_msise00.py

@@ -4,8 +4,10 @@
 
 """
 import scipy.constants
+import xarray as xr
 from .atmosphere import Atmosphere
-import numpy.typing as npt
+from ..types import NDArray_N
+
 
 try:
     import msise00
@@ -21,16 +23,16 @@ class AtmMSISE00(Atmosphere):
 
     def density(
         self,
-        time: npt.ArrayLike,
-        lat: npt.ArrayLike,
-        lon: npt.ArrayLike,
-        alt: npt.ArrayLike,
+        time: NDArray_N,
+        lat: NDArray_N,
+        lon: NDArray_N,
+        alt: NDArray_N,
         f107: float = 80.0,
         f107s: float = 80.0,
         Ap: float = 4.0,
         mass_densities: bool = False,
         **kwargs
-    ):
+    ) -> xr.Dataset:
         """TODO: Write docstring
 
         returns density in [m^-3]

{metablate-0.1.0 → metablate-0.3.0}/src/metablate/atmosphere/atm_pymsis.py

@@ -39,17 +39,20 @@ class AtmPymsis(Atmosphere):
         lat: npt.ArrayLike,
         lon: npt.ArrayLike,
         alt: npt.ArrayLike,
-        f107: npt.ArrayLike = None,
-        f107s: npt.ArrayLike = None,
-        aps: npt.ArrayLike = None,
+        f107: npt.ArrayLike | None = None,
+        f107s: npt.ArrayLike | None = None,
+        aps: npt.ArrayLike | None = None,
         mass_densities: bool = False,
         version: Union[float, str] = 2.1,
+        as_dataset: bool = True,
         **kwargs
-    ):
-        """TODO: Write docstring
-
-        returns density in [m^-3]
+    ) -> xr.Dataset | dict[str, xr.Variable]:
+        """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")
@@ -77,34 +80,38 @@ class AtmPymsis(Atmosphere):
         if len(result.shape) == 2:
             result = result.reshape(result.shape[0], 1, 1, 1, result.shape[1])
 
-        result = xr.Dataset(
-            {
-                "Total": (["time", "lon", "lat", "alt"], result[:, :, :, :, 0]),
-                "N2": (["time", "lon", "lat", "alt"], result[:, :, :, :, 1]),
-                "O2": (["time", "lon", "lat", "alt"], result[:, :, :, :, 2]),
-                "O": (["time", "lon", "lat", "alt"], result[:, :, :, :, 3]),
-                "He": (["time", "lon", "lat", "alt"], result[:, :, :, :, 4]),
-                "H": (["time", "lon", "lat", "alt"], result[:, :, :, :, 5]),
-                "Ar": (["time", "lon", "lat", "alt"], result[:, :, :, :, 6]),
-                "N": (["time", "lon", "lat", "alt"], result[:, :, :, :, 7]),
-                "AnomalousO": (["time", "lon", "lat", "alt"], result[:, :, :, :, 8]),
-                "NO": (["time", "lon", "lat", "alt"], result[:, :, :, :, 9]),
-                "Temperature": (["time", "lon", "lat", "alt"], result[:, :, :, :, 10]),
-            },
-            coords={
-                "time": time,
-                "lon": lon,
-                "lat": lat,
-                "alt": alt,
-            },
-            attrs=dict(
-                f107 = f107,
-                f107s = f107s,
-                aps = aps,
-                mass_densities = mass_densities,
-                version = version,
+        variables = {
+            "Total": (["time", "lon", "lat", "alt"], result[:, :, :, :, 0]),
+            "N2": (["time", "lon", "lat", "alt"], result[:, :, :, :, 1]),
+            "O2": (["time", "lon", "lat", "alt"], result[:, :, :, :, 2]),
+            "O": (["time", "lon", "lat", "alt"], result[:, :, :, :, 3]),
+            "He": (["time", "lon", "lat", "alt"], result[:, :, :, :, 4]),
+            "H": (["time", "lon", "lat", "alt"], result[:, :, :, :, 5]),
+            "Ar": (["time", "lon", "lat", "alt"], result[:, :, :, :, 6]),
+            "N": (["time", "lon", "lat", "alt"], result[:, :, :, :, 7]),
+            "AnomalousO": (["time", "lon", "lat", "alt"], result[:, :, :, :, 8]),
+            "NO": (["time", "lon", "lat", "alt"], result[:, :, :, :, 9]),
+            "Temperature": (["time", "lon", "lat", "alt"], result[:, :, :, :, 10]),
+        }
+        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():

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

@@ -5,7 +5,8 @@ from copy import copy
 
 import scipy.constants as constants
 import numpy as np
-import numpy.typing as npt
+import xarray as xr
+from ..types import NDArray_N
 
 logger = logging.getLogger(__name__)
 
@@ -58,7 +59,7 @@ 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]):
         self.species = {}
         for s in supported_species:
             if isinstance(s, Species):
@@ -71,10 +72,10 @@ class Atmosphere:
     @abstractmethod
     def density(
         self,
-        time: npt.ArrayLike,
-        lat: npt.ArrayLike,
-        lon: npt.ArrayLike,
-        alt: npt.ArrayLike,
+        time: np.datetime64,
+        lat: NDArray_N,
+        lon: NDArray_N,
+        alt: NDArray_N,
         **kwargs
-    ):
+    ) -> xr.Dataset:
         pass

metablate-0.3.0/src/metablate/material.py

@@ -0,0 +1,110 @@
+"""
+# Meteoroid material physics
+
+[Fe SiO2 C C] mean molecular mass per target atoms corresponding
+to the different meteoroid densities, see Rogers p. 1344 values
+are from Tielens et al.
+
+Mean molecular mass of ablated vapor assuming that all products
+liberated from the meteoroid by thermal ablation were released
+in complete molecular form.
+
+"""
+
+from dataclasses import asdict
+import logging
+from copy import copy
+from scipy import constants
+from .types import Material
+
+logger = logging.getLogger(__name__)
+
+MATERIALS = {}
+
+iron = Material(
+    bulk_density=7800.0,
+    mean_atomic_mass=56.0 * constants.u,
+    latent_heat_of_fusion_vapourization=6.0e6,
+    specific_heat=1200,
+    average_atomic_number=26,
+    surface_binding_energy=4.1,
+    ablated_vapour_mean_molecular_mass=56.0 * constants.u,
+    penetration_correction_parameter_K=0.35,
+    clausius_clapeyron_coeff_A=10.6,
+    clausius_clapeyron_coeff_B=16120.0,
+)
+MATERIALS["iron"] = iron
+
+asteroidal = Material(
+    bulk_density=3300.0,
+    mean_atomic_mass=20.0 * constants.u,
+    latent_heat_of_fusion_vapourization=6.0e6,
+    specific_heat=1200,
+    average_atomic_number=10,
+    surface_binding_energy=6.4,
+    ablated_vapour_mean_molecular_mass=50.0 * constants.u,
+    penetration_correction_parameter_K=0.1,
+    clausius_clapeyron_coeff_A=10.6,
+    clausius_clapeyron_coeff_B=13500.0,
+)
+MATERIALS["asteroidal"] = asteroidal
+
+cometary = Material(
+    bulk_density=1000.0,
+    mean_atomic_mass=12.0 * constants.u,
+    latent_heat_of_fusion_vapourization=6.0e6,
+    specific_heat=1200,
+    average_atomic_number=6,
+    surface_binding_energy=4.0,
+    ablated_vapour_mean_molecular_mass=20.0 * constants.u,
+    penetration_correction_parameter_K=0.65,
+    clausius_clapeyron_coeff_A=10.6,
+    clausius_clapeyron_coeff_B=13500.0,
+)
+MATERIALS["cometary"] = cometary
+
+porous = Material(
+    bulk_density=300.0,
+    mean_atomic_mass=12.0 * constants.u,
+    latent_heat_of_fusion_vapourization=6.0e6,
+    specific_heat=1200,
+    average_atomic_number=6,
+    surface_binding_energy=4.0,
+    ablated_vapour_mean_molecular_mass=20.0 * constants.u,
+    penetration_correction_parameter_K=0.65,
+    clausius_clapeyron_coeff_A=10.6,
+    clausius_clapeyron_coeff_B=13500.0,
+)
+MATERIALS["porous"] = porous
+
+
+def available():
+    """List currently available meteoroid materials."""
+    return list(MATERIALS.keys())
+
+
+def get(material, as_dict=True):
+    """Returns the physical parameters of the meteoroid based on its material.
+
+    Parameters
+    ----------
+    material : str
+        name of material
+    as_dict : bool
+        Return data as dict instead of as a Material instance
+
+    Returns
+    -------
+    Material or dict
+        Dictionary of all available material parameters (float or None)
+    """
+
+    _material = material.lower().strip()
+    if _material not in MATERIALS:
+        raise ValueError(
+            f'No data exists for material "{_material}"\n' f"Avalible materials are: {available()}"
+        )
+    if as_dict:
+        return asdict(MATERIALS[_material])
+    else:
+        return copy(MATERIALS[_material])

metablate-0.3.0/src/metablate/models/__init__.py

@@ -0,0 +1,6 @@
+from . import dimant_oppenheim_2017
+from . import kero_szasz_2008
+from . import stulov_mirskii_vislyi_1995
+from . import simple_motion
+from . import alpha_beta_2026
+from . import simple_ablation_2026