natal-core 0.1.3

Numba-Accelerated Toolkit for Analysis of Lifecycles, a high-performance forward-time population genetics simulation engine especially designed for gene drive modeling.

⚡️ NATAL Core

Numba-Accelerated Toolkit for Analysis of Lifecycles

NATAL Core is a high-performance forward-time population genetics simulation engine that supports configurable lifecycles of species. It supports age-structured and discrete-generation populations, sperm storage, genetic presets, hook-based interventions, and simulation kernels accelerated by Numba. NATAL Core is especially useful for modeling gene drive systems in insect populations, but its flexible architecture allows it to be applied to a wide range of population genetics scenarios.

NATAL Core is part of the NATAL project. The full project also includes NATAL Inferencer, a toolkit for parameter inference in population genetics models based on NATAL Core.

Key Features

• 🪲 Forward-time configurable population modeling (age-structured and discrete-generation).
• 🧬 Genetic architecture definition with chromosomes, loci, and alleles.
• 🚀 Numba-accelerated kernels for high performance.
• 🧩 Built-in genetic presets, especially for homing drives and toxin-antidote drives.
• 🪝 Hook system for custom interventions during simulation.
• 🔍 Observation and filtering utilities for downstream analysis.
• 🗺️ Spatial simulation support across multiple demes.

Installation

1. Create a virtual environment

It is strongly recommended to use a virtual environment to manage dependencies.

Choose one of the following commands. Python 3.12 is recommended, but any Python version >= 3.9 should work.

uv venv --python 3.12 .venv            # uv (recommended)
python -m venv .venv                   # venv (please ensure Python >= 3.9 is used)
conda create -n natal-env python=3.12  # conda

On Windows, you can run py -3.12 -m venv .venv to specify Python 3.12 as the interpreter for the virtual environment.

2. Activate the virtual environment

Linux / macOS:

source .venv/bin/activate    # uv / venv
conda activate natal-env     # conda

Windows:

.venv\Scripts\activate       # uv / venv
conda activate natal-env     # conda

3. Install NATAL Core

uv pip install natal-core
# or
pip install natal-core

A Minimal Example

import natal as nt
from natal.ui import launch

# 1. Define the genetics architecture of a species
sp = nt.Species.from_dict(
    name="TestSpecies",
    structure={
        "chr1": {"loc1": ["WT", "Dr", "R2", "R1"]}
    },
    gamete_labels=["default", "cas9_deposited"]
)

# 2. Define a drive using built-in presets
drive = nt.HomingDrive(
    name="TestHoming",
    drive_allele="Dr",
    cas9_allele="Dr",
    target_allele="WT",
    resistance_allele="R2",
    functional_resistance_allele="R1",
    drive_conversion_rate=0.95,
    late_germline_resistance_formation_rate=0.9,
    functional_resistance_ratio=0.001,
    embryo_resistance_formation_rate=0.0,
    viability_scaling=1.0,
    fecundity_scaling={"female": 0.0},
    fecundity_mode="recessive",
    cas9_deposition_glab="cas9_deposited"
)

# 3. Define a release event using hooks
@nt.hook(event="first", priority=0)
def release_drive_carriers():
    return [
        nt.Op.add(genotypes="WT|Dr", ages=1, sex="male", delta=500, when="tick == 10")
    ]

# 4. Build a panmictic population
pop = (nt.DiscreteGenerationPopulation
    .setup(
        species=sp,
        name="TestPop",
        stochastic=True
    )
    .initial_state(
        individual_count={
        "male": {"WT|WT": 50000}, "female": {"WT|WT": 50000}
        }
    )
    .reproduction(
        eggs_per_female=100
    )
    .competition(
        low_density_growth_rate=6.0,
        carrying_capacity=100000,
        juvenile_growth_mode="concave"
    )
    .presets(drive).hooks(release_drive_carriers).build())

# 5. Launch interactive WebUI and run simulation
launch(pop)

For more ready-to-run examples, see the demos directory in the GitHub repository.

Documentation and Links

• Documentation (English): https://natal-core.readthedocs.io/en/latest/
• 文档 (中文): https://natal-core.readthedocs.io/zh-cn/latest/
• GitHub repository: https://github.com/jyzhu-pointless/natal-core
• PyPI package: https://pypi.org/project/natal-core/

License

This project is licensed under the MIT License.