crimsons 0.1.0__tar.gz

crimsons-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+      - run: ruff check src tests

crimsons-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+
+yields_data/
+
+# example/run artifacts
+/cache/
+*.h5
+*.csv
+!tests/**/*.h5

crimsons-0.1.0/.readthedocs.yml

@@ -0,0 +1,22 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    # Doc-build dependencies (mkdocs-material, mkdocstrings, ...)
+    - requirements: docs/requirements.txt
+    # The package itself, so mkdocstrings can import `crimsons` and pull
+    # live docstrings/signatures for the API reference. Adjust the path
+    # if your pyproject.toml / setup.py lives somewhere other than the
+    # repository root.
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+mkdocs:
+  configuration: mkdocs.yml

crimsons-0.1.0/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "crimsons: stochastic chemical enrichment of stellar populations"
+version: 0.1.0
+date-released: 2026-07-31
+authors:
+  - family-names: "Your Last Name"
+    given-names: "Your First Name"
+    affiliation: "Your Institution"
+repository-code: "https://github.com/yourusername/crimsons"
+license: MIT

crimsons-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lapo Querci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crimsons-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: crimsons
+Version: 0.1.0
+Summary: Stochastic chemical enrichment of stellar populations (SNII, SNIa, AGB) from a sampled IMF.
+Project-URL: Homepage, https://github.com/lquerci/crimsons
+Project-URL: Issues, https://github.com/lquerci/crimsons/issues
+Author-email: Lapo Querci <lapo.querci@unifi.it>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Requires-Dist: h5py>=3.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: tqdm>=4.70
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.9; extra == 'docs'
+Provides-Extra: parallel
+Requires-Dist: joblib; extra == 'parallel'
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# CRIMSONS
+
+Chemical evolution with the Random sampling of the Initial Mass function: Studying the Origin of Nucleosynthetic Stellar products
+
+This python package performs the stochastic chemical-enrichment simulations of stellar populations: sample
+an initial mass function, evolve it through core-collapse supernovae, AGB
+winds, Type Ia supernovae and (optionally) pair-instability supernovae,
+and get back the time-resolved abundances of 30 elements released to the
+interstellar medium.
+
+> **Status:** first public version
+
+## Install
+
+```bash
+pip install crimsons 
+```
+
+or from source
+
+```bash
+git clone https://github.com/lquerci/crimsons.git
+cd crimsons
+pip install .
+```
+
+
+## Quickstart
+
+```python
+from crimsons import Kroupa2001, Simulation
+
+sim = Simulation(
+    imf=Kroupa2001(),
+    mass_formed=1e6,
+    metallicity=0.0142,
+    n_realizations=20,
+    seed=42,
+)
+result = sim.run()
+mean_fe = result["Fe"].mean()
+```
+
+## Documentation
+
+Full documentation -- installation, examples, the physics behind each
+piece, and the complete API reference -- lives at
+`https://crimsons.readthedocs.io`.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

crimsons-0.1.0/README.md

@@ -0,0 +1,52 @@
+# CRIMSONS
+
+Chemical evolution with the Random sampling of the Initial Mass function: Studying the Origin of Nucleosynthetic Stellar products
+
+This python package performs the stochastic chemical-enrichment simulations of stellar populations: sample
+an initial mass function, evolve it through core-collapse supernovae, AGB
+winds, Type Ia supernovae and (optionally) pair-instability supernovae,
+and get back the time-resolved abundances of 30 elements released to the
+interstellar medium.
+
+> **Status:** first public version
+
+## Install
+
+```bash
+pip install crimsons 
+```
+
+or from source
+
+```bash
+git clone https://github.com/lquerci/crimsons.git
+cd crimsons
+pip install .
+```
+
+
+## Quickstart
+
+```python
+from crimsons import Kroupa2001, Simulation
+
+sim = Simulation(
+    imf=Kroupa2001(),
+    mass_formed=1e6,
+    metallicity=0.0142,
+    n_realizations=20,
+    seed=42,
+)
+result = sim.run()
+mean_fe = result["Fe"].mean()
+```
+
+## Documentation
+
+Full documentation -- installation, examples, the physics behind each
+piece, and the complete API reference -- lives at
+`https://crimsons.readthedocs.io`.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

crimsons-0.1.0/TODO.md

@@ -0,0 +1,25 @@
+# Project
+
+Project Description
+
+<em>[TODO.md spec & Kanban Board](https://bit.ly/3fCwKfM)</em>
+
+### Todo
+
+- [ ] README.md  
+- [ ] publish on PyPi  
+- [ ] Check all function comments  
+- [ ] Add IMF weighted chem enrich  
+- [ ] Check SNIa model  
+
+### In Progress
+
+- [ ] Finish documentation  
+
+### Done ✓
+
+- [x] divide explosion energy in the output  
+- [x] Fiducial model as default  
+- [x] Parallelize  
+- [x] Add logic to switch to rolled enrichemnt and not rolled  
+

crimsons-0.1.0/docs/api/core.md

@@ -0,0 +1,25 @@
+# Results & Config (`crimsons.results`, `crimsons.config`, `crimsons.chemistry`)
+
+The data returned by a run (`EnrichmentResult`), the configuration that
+produced it (`RunConfig`, also the basis for cache keys -- see
+[Caching & Persistence](../examples/caching-results.md)), and the
+tracked-element / solar-metallicity constants shared across the package.
+
+## Results
+
+::: crimsons.results
+    options:
+      members_order: source
+
+## Run configuration
+
+::: crimsons.config
+    options:
+      members_order: source
+
+## Chemistry constants
+
+::: crimsons.chemistry
+    options:
+      members_order: source
+      show_source: true

crimsons-0.1.0/docs/api/enrichment.md

@@ -0,0 +1,12 @@
+# Enrichment Engine (`crimsons.enrichment`)
+
+The per-realization loop `Simulation.run()` calls once per realization:
+sample the IMF into log-mass bins, route each bin (or the population as a
+whole, for `SNIa`) through the configured channels, and bin the resulting
+events onto a shared time grid. See
+[Stochastic Sampling](../customize/sampling.md) for the binned Monte Carlo
+approach this implements.
+
+::: crimsons.enrichment.engine
+    options:
+      members_order: source

crimsons-0.1.0/docs/api/imf.md

@@ -0,0 +1,31 @@
+# Initial Mass Functions (`crimsons.imf`)
+
+Base class, exact broken-power-law implementations, and a general
+numerical implementation for arbitrary shapes. See
+[Customize: Initial Mass Function](../customize/imf.md) for the underlying
+model and [Custom IMF Shapes](../examples/custom-imf.md) for usage
+examples.
+
+## Base class
+
+::: crimsons.imf.base
+    options:
+      members_order: source
+
+## Metallicity-adaptive default mass range
+
+::: crimsons.imf.mass_range
+    options:
+      members_order: source
+
+## Broken power laws (Salpeter, Kroupa, Flat)
+
+::: crimsons.imf.standard
+    options:
+      members_order: source
+
+## Arbitrary shapes
+
+::: crimsons.imf.functional
+    options:
+      members_order: source

crimsons-0.1.0/docs/api/index.md

@@ -0,0 +1,40 @@
+# API Reference
+
+This section is generated directly from docstrings in `src/crimsons` by
+[mkdocstrings](https://mkdocstrings.github.io/) -- every page's "Source
+code" toggle shows the real implementation alongside its documentation,
+so it never drifts out of sync with what's actually shipped.
+
+## Package layout
+
+| Page | Module(s) | Covers |
+|---|---|---|
+| [Simulation](simulation.md) | `crimsons.simulation.ensemble` | The `Simulation` class -- ties everything below together into an ensemble run. |
+| [Initial Mass Functions](imf.md) | `crimsons.imf.*` | `IMF` base class, `Salpeter1955`/`Kroupa2001`/`FlatIMF`/`BrokenPowerLawIMF`, `FunctionalIMF`, and the metallicity-adaptive mass-range policy. |
+| [Stellar Lifetimes](stars.md) | `crimsons.stars.lifetimes` | `LifetimeFunction` base class and the bundled `StellarLifetime` model. |
+| [Yields & Channels](yields.md) | `crimsons.yields.*` | `Channel`/`MassRangeChannel`/`PopulationChannel`, `YieldTable`/`StochasticYieldTable`, the bundled `SNII`/`AGB`/`PISN`/`SNIa` channels, and yield-table I/O. |
+| [Enrichment Engine](enrichment.md) | `crimsons.enrichment.engine` | The per-realization sampling/enrichment loop `Simulation` drives. |
+| [Results & Config](core.md) | `crimsons.results`, `crimsons.config`, `crimsons.chemistry` | `EnrichmentResult`, `RunConfig`, and the tracked-element/metallicity constants. |
+| [I/O & Caching](io.md) | `crimsons.io.*` | HDF5 read/write for `EnrichmentResult`, and the config-hash-based run cache. |
+
+## Top-level imports
+
+Everything most users need is re-exported from the `crimsons` package
+itself:
+
+```python
+from crimsons import (
+    AGB, PISN, SNII, SNIa,               # channels
+    ELEMENTS, ZSUN,                       # constants
+    EnrichmentResult,
+    FunctionalIMF, Kroupa2001, Salpeter1955,  # IMFs
+    Simulation,
+    StellarLifetime,
+    default_channels, describe_available_model, list_available_models,
+)
+```
+
+`FlatIMF`, `BrokenPowerLawIMF`, and the individual `Channel`/`YieldTable`
+base classes aren't re-exported at the top level -- import them from their
+own submodule (e.g. `from crimsons.imf.standard import BrokenPowerLawIMF`)
+when subclassing or introspecting directly.

crimsons-0.1.0/docs/api/io.md

@@ -0,0 +1,14 @@
+# I/O & Caching (`crimsons.io`)
+
+HDF5 serialization for `EnrichmentResult`, and the config-hash-based run
+cache that `Simulation.run(cache_dir=...)` uses. See
+[Caching & Persistence](../examples/caching-results.md) for usage
+examples.
+
+::: crimsons.io.hdf5
+    options:
+      members_order: source
+
+::: crimsons.io.cache
+    options:
+      members_order: source

crimsons-0.1.0/docs/api/simulation.md

@@ -0,0 +1,10 @@
+# Simulation (`crimsons.simulation`)
+
+The top-level entry point: ties an IMF, a lifetime function, and a set of
+channels together into an ensemble of Monte Carlo realizations. See
+[Quickstart](../getting-started/quickstart.md) for a walkthrough and
+[Physics Overview](../customize/index.md) for what happens inside `run()`.
+
+::: crimsons.simulation.ensemble
+    options:
+      members_order: source

crimsons-0.1.0/docs/api/stars.md

@@ -0,0 +1,9 @@
+# Stellar Lifetimes (`crimsons.stars`)
+
+Maps stellar mass and metallicity to a main-sequence(-ish) lifetime in Myr.
+See [Stellar Lifetimes](../customize/lifetimes.md) for the
+underlying fits.
+
+::: crimsons.stars.lifetimes
+    options:
+      members_order: source

crimsons-0.1.0/docs/api/yields.md

@@ -0,0 +1,25 @@
+# Yields & Channels (`crimsons.yields`)
+
+Yield-table data structures, the `Channel` interface, the bundled
+SNII/AGB/PISN/SNIa channels, and HDF5/CSV table loading. See
+[Enrichment Channels](../customize/channels.md) for the underlying
+model and [Selecting Yield Models](../examples/yield-models.md) for usage
+examples.
+
+## Channels & yield-table data structures
+
+::: crimsons.yields.base
+    options:
+      members_order: source
+
+## Bundled channels (SNII, AGB, PISN, SNIa)
+
+::: crimsons.yields.channels
+    options:
+      members_order: source
+
+## Loading yield tables
+
+::: crimsons.yields.io
+    options:
+      members_order: source

crimsons-0.1.0/docs/changelog.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to CRIMSONS are documented here, following the spirit
+of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/){: target="_blank" } and
+[Semantic Versioning](https://semver.org/){: target="_blank" }.
+
+## [0.1.0]
+
+Initial development release.
+
+- Core simulation loop (`Simulation`, `EnrichmentResult`, `RunConfig`).
+- IMFs: `Salpeter1955`, `Kroupa2001`, `FlatIMF`, `FunctionalIMF`, `Chabrier2003`.
+- Channels: `SNII`, `AGB`, `PISN`, `SNIa` (DTD and single-burst modes).
+- `StellarLifetime` (Raiteri et al. 1996 / Schaerer et al. 2002).
+- HDF5-backed yield-table loading with fixed and stochastic model
+  parameters.
+- Result caching keyed on a hashed `RunConfig`.
+
+[Unreleased]: https://github.com/your-org/crimsons/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/your-org/crimsons/releases/tag/v0.1.0

crimsons-0.1.0/docs/contributing.md

@@ -0,0 +1,10 @@
+# Contributing
+
+All efforts to improve CRIMSONS are wellcomed. We ask any contributor to follow the simple four steps below:
+
+1. Fork and branch from `main`.
+2. Keep changes focused; add/update tests and docs alongside code changes.
+3. Make sure `pytest` and `mkdocs build --strict` both pass locally.
+4. Open a PR describing what changed and why.
+
+For any questions, bugs or issue, please contact: lapo.querci1@unifi.it

crimsons-0.1.0/docs/customize/channels.md

@@ -0,0 +1,141 @@
+# Enrichment Channels
+
+A **channel** decides which stars enrich the ISM, when their enrichment
+arrives, and how much of each element they release. CRIMSONS has two kinds:
+
+- **`MassRangeChannel`** -- triggered purely by a star's initial mass;
+  enrichment arrives at the end of that star's life (`SNII`, `AGB`,
+  `PISN`).
+- **`PopulationChannel`** -- driven by the population as a whole rather
+  than any single star's mass (`SNIa`, via a delay-time distribution).
+
+`default_channels()` returns `SNII() + AGB() + SNIa()`. Add `PISN()`
+yourself for Population III / extremely metal-poor runs.
+
+## What it is
+
+### Mass-triggered channels
+
+| Channel | Default mass window | Physical picture |
+|---|---|---|
+| `AGB` | $2$–$8\,M_\odot$ | Low/intermediate-mass stars enriching via stellar winds; primary $s$-process and light elements (C, N, F). |
+| `SNII` | $8$–$40\,M_\odot$ | Core-collapse supernovae; hydrostatic burning up to iron-group elements plus explosive nucleosynthesis. |
+| `PISN` | $140$–$260\,M_\odot$ | Pair-instability supernovae: complete disruption, no compact remnant, of very massive, metal-free/extremely metal-poor stars. Effectively Population III only. |
+
+A star contributes to a channel if its mass falls in `[mass_min,
+mass_max]`; its delay time is simply its stellar lifetime (see
+[Stellar Lifetimes](lifetimes.md)); and its yield comes from that
+channel's yield table (see [Selecting Yield Models](../examples/yield-models.md)),
+evaluated at its mass and the population's metallicity.
+
+### SN Ia: a delay-time distribution over the population
+
+SN Ia doesn't select individual progenitor stars by mass -- it treats the
+whole population's eventual SN Ia rate as a population-level statistic.
+Explosions follow a delay-time distribution (DTD) which is normalized to
+integrate to 1 over the run's `time_grid` and is scaled by `rate_per_msun`
+(SN Ia per $M_\odot$ of stars formed) to give an absolute expected number
+of explosions per time bin:
+
+$$
+\dot N_{\rm Ia}(t) \propto \Psi(\tau)
+$$
+
+Two shapes are available for $\Psi(\tau)$ ($\tau$ in Myr):
+
+=== "Maoz+12 (default)"
+
+    A power law, with support bounded below by `min_time`:
+
+    $$
+    \Psi(\tau) \propto \left(\frac{\tau}{\tau_{\min}}\right)^{-1.12}, \quad \tau > \tau_{\min}
+    $$
+
+    Default literature rate: `rate_per_msun = 0.0013`.
+
+=== "Mannucci+06 / Matteucci+06"
+
+    A double-Gaussian-in-log-time shape, split at $t_0 = 10^{7.93}\,\mathrm{yr}$
+    into a "prompt" and a "delayed" component:
+
+    $$
+    \log_{10}\Psi(\tau) =
+    \begin{cases}
+    1.4 - 50\,(\log_{10}t + 7.7)^2 & t \le t_0 \\
+    -0.8 - 0.9\,(\log_{10}t - 8.7)^2 & t > t_0
+    \end{cases}
+    \quad (t = \tau\ \text{in yr})
+    $$
+
+    Default literature rate: `rate_per_msun = 0.0025`.
+
+Either shape's support is bounded by the progenitor mass range's
+(default $3$–$8\,M_\odot$) lifetimes: the most massive progenitor sets
+$\tau_{\min}$, the least massive sets $\tau_{\max}$, both evaluated through
+whichever `lifetime_fn` the `Simulation` uses. The (generally fractional)
+expected explosion count per time bin is converted to an integer count via
+**deterministic remainder carry-over** -- each bin's leftover fraction
+rolls into the next bin's expected count -- rather than a random (e.g.
+Poisson) draw.
+
+!!! note "SN Ia is deterministic across realizations, by default"
+    Because neither the DTD shape, its normalization, nor the
+    integerization step involves the realization's random number
+    generator, every realization in an ensemble gets an **identical**
+    SN Ia contribution (same `mass_formed`, `metallicity`, and
+    `time_grid` in, same result out) -- unless you configure a yield
+    table with a stochastic model parameter (see
+    [Selecting Yield Models](../examples/yield-models.md)). The
+    realization-to-realization *scatter* you see in an
+    `EnrichmentResult` comes from the stochastic IMF sampling behind
+    `SNII`/`AGB`/`PISN`, not from `SNIa`.
+
+## Customizing
+
+### Changing a channel's mass window
+
+The mass windows in the table above are constructor defaults, not
+physical constants -- pass `mass_min=`/`mass_max=` to any of the three
+mass-triggered channels to change the window (e.g. for a different
+progenitor model or literature convention):
+
+```python
+from crimsons import SNII
+
+snii = SNII(mass_min=10.0, mass_max=25.0)
+```
+
+### Choosing SN Ia's shape and mode
+
+`SNIa` supports `dtd_shape="maoz"` (default) or `dtd_shape="mannucci"`
+for the two formulas above, plus a `mode="single_burst"` alternative --
+the discretized limit of a delta-function DTD, where every eligible SN Ia
+explodes at one fixed delay (`burst_delay_myr`) after formation instead of
+following a distribution:
+
+```python
+from crimsons import SNIa
+
+snia = SNIa(dtd_shape="mannucci")
+snia = SNIa(mode="single_burst", burst_delay_myr=1000.0, rate_per_msun=0.001)
+```
+
+See [Selecting Yield Models](../examples/yield-models.md#sn-ia-delay-time-distribution-vs-single-burst)
+for the additional parameter walkthrough.
+
+### Choosing a yield model
+
+Each channel also takes `model=`/`model_params=` to select *which*
+tabulated nucleosynthesis calculation it draws yields from (independent
+of the mass window above) -- see
+[Selecting Yield Models](../examples/yield-models.md) for the full
+walkthrough, including stochastic (per-star) model parameters and
+supplying your own yield tables entirely.
+
+### Writing your own channel
+
+Subclass `MassRangeChannel` for another mass-triggered channel, or
+`Channel`/`PopulationChannel` directly for something that doesn't fit
+either existing pattern -- see
+[`Channel`][crimsons.yields.base.Channel] in the API reference for the
+methods a channel must implement.