Simulation

Forward-time genetics simulation loop. Simulation orchestrates meiosis, architecture evaluation, filtering, statistics, and callbacks across generations.

New simulation loop for the refactored xftsim.

Simulation: forward-time genetics simulation using the new data structures, architecture DAG, and mate assignment system.

class xftsim.sim.Simulation(founder_haplotypes, architecture, mating_regime, recombination_map, retain_haplotypes=1, retain_phenotypes=2, callbacks=None, filters=None, statistics=None, seed=None)[source]

Bases: object

Forward-time genetics simulation.

Orchestrates the simulation loop: for each generation, performs meiosis (recombination), computes phenotypes via the architecture DAG, applies filters, computes statistics, and runs callbacks. History dicts are pruned according to configurable retention policies.

Parameters:

  • founder_haplotypes (HaplotypeOperator) – Generation-0 haplotypes (DenseHaplotypeArray or GraphHaplotypeOperator).

  • architecture (Architecture) – Phenogenetic architecture (DAG of ArchNodes).

  • mating_regime (RandomMating or LinearAssortativeMating) – Mating strategy that produces MateAssignment each generation.

  • recombination_map (RecombinationMap) – Recombination probabilities for meiosis.

  • retain_haplotypes (int) – How many past generations of haplotypes to keep. Default 1.

  • retain_phenotypes (int) – How many past generations of phenotypes to keep. Default 2.

  • callbacks (list[callable], optional) – Functions called after each generation with callback(sim). Set sim.stop = True inside a callback for early stopping.

  • filters (dict[str, Filter], optional) – Named filters to run after each generation’s phenotype computation.

  • statistics (list[Statistic], optional) – Statistics to compute after each generation.

  • seed (int, optional) – Random seed for reproducibility.

Parameters:
generation

Current generation number.

Type:

int

haplotype_history

Generation -> haplotype data mapping (pruned by retention policy).

Type:

dict[int, HaplotypeOperator]

phenotype_history

Generation -> phenotype data mapping (pruned by retention policy).

Type:

dict[int, PhenotypeArray]

pedigree_history

Generation -> pedigree mapping (pruned by retention policy).

Type:

dict[int, PedigreeArray]

results

Statistics results for each completed generation.

Type:

list[GenerationResult]

stop

Set to True inside a callback to halt the simulation.

Type:

bool

Examples

>>> from xftsim.founders import founder_haplotypes_uniform_AFs
>>> from xftsim.effect import AdditiveEffects
>>> from xftsim.arch import Architecture, GeneticComponent, NoiseComponent
>>> from xftsim.mate import RandomMating
>>> from xftsim.reproduce import RecombinationMap
>>> import numpy as np
>>> hap = founder_haplotypes_uniform_AFs(n=100, m=50)
>>> eff = AdditiveEffects.from_h2(h2=0.5, m=50, seed=42)
>>> arch = Architecture()
>>> arch.add('Y.G', GeneticComponent(eff))
>>> arch.add('Y.E', NoiseComponent(0.5))
>>> arch.add('Y', AggregationComponent('Y.G + Y.E'))
>>> rmap = RecombinationMap.uniform(m=50, p=0.01)
>>> sim = Simulation(hap, arch, RandomMating(), rmap, seed=1)
>>> sim.run(n_generations=3)
>>> sim.generation
2
Parameters:
classmethod from_checkpoint(dir_path, mating_regime=None, recombination_map=None, callbacks=None, filters=None, statistics=None)[source]

Reconstruct a simulation from a checkpoint directory.

Parameters:

  • dir_path (str) – Path to checkpoint directory (created by save_simulation_checkpoint).

  • mating_regime (optional) – Override the saved mating regime. If None, uses the saved one.

  • recombination_map (RecombinationMap, optional) – Override the saved recombination map. If None, uses the saved one.

  • callbacks (list[callable], optional) – Callbacks for continued execution.

  • filters (dict, optional) – Filters for continued execution.

  • statistics (list, optional) – Statistics for continued execution.

Return type:

Simulation

Returns:

Simulation – A simulation ready for continued execution via run().

Parameters:
property haplotypes: HaplotypeOperator

Current generation’s haplotypes.

property phenotypes: PhenotypeArray

Current generation’s phenotypes.

run(n_generations)[source]

Run the simulation for n_generations.

Generation 0: compute phenotypes from founder haplotypes, assign mates. Generation t>0: meiosis -> compute phenotypes -> assign mates.

Parameters:

n_generations (int) – Number of generations to simulate (including gen 0).

Parameters:

n_generations (int)

Return type:

None

continue_run(n_additional)[source]

Continue a simulation for n_additional generations from current state.

Used after loading from a checkpoint via from_checkpoint().

Parameters:

n_additional (int) – Number of additional generations to simulate.

Parameters:

n_additional (int)

Return type:

None