DEVELOPMENT.md
Source:DEVELOPMENT.md
Guidance for AI coding agents (and people) extending or modifying evomod2. For using the package, see AGENTS.md; the conventions listed there (standard deviations, per-allele rates, genome layout, optimum carry-over) apply to new code too.
Layout
-
src/evomod.h: the C++ component interfaces (Architecture,Mutation,Fitness,Recombination) and their implementations;src/components.cppbuilds components from the R lists (make_*()factories);src/simulate.cpphas the generation loop (evolve_cpp) and C++ helpers exported to R. -
R/: constructors (architecture.R,model.R,regimes.R,recombination.R),evolve.R, accessors and analysis (accessors.R,statistics.R),plot.R. -
tests/testthat/: unit tests;validation/: cross-checks against independent implementations (EvoMod.jl, the original C code), not run in CI. -
inst/examples/: command-line experiments;inst/extdata/: stored summaries used by the results vignettes;vignettes/;_pkgdown.ymlanddocs/(the website).
The generation loop
evolve_cpp() in src/simulate.cpp runs the regimes. In every generation, in this order:
- the optimum moves (
directional():theta += delta_theta;fluctuating(): a jump after everyeverygenerations); - fitness is computed from the current phenotypes (all ones under drift);
- reproduction:
- Wright-Fisher: every genome mutates (
Mutation::mutate),nsires andndames are drawn with probability proportional to fitness, andRecombination::offspringbuilds the offspring into a separate buffer, which is then swapped in (parents are never overwritten); - Moran:
nevents; each replaces a random individual by an offspring of two parents drawn from a Fenwick tree of fitnesses, the offspring then mutates, and only its fitness is updated;
- Wright-Fisher: every genome mutates (
- genotypic values (
Architecture::genotypic_value) and phenotypes (x + Normal(0, env_sd)) are computed; - statistics are recorded when
generation % record_every == 0.
The optimum carries over between regimes; a regime resets it only when the user gives theta (reset_theta).
Interfaces in detail
-
Architecture:genotypic_value(genome)(traits vector),local_effects(genome)(traits x loci: the change in genotypic value when a locus is set to the reference genotype, all zeros), and optionallyallele_effects(genome)(traits x alleles) when genotypic values are sums of allele effects; return an empty matrix otherwise.allele_effectsenables the exactg_decomposition()and the recorded genic part of G. -
Mutation:mutate(genome)(one generation of mutation, using binomial numbers of events),mutate_one(genome)(exactly one event, at a site chosen in proportion to the rates; used bymutational_covariance()), andexpected_mutations(genome)(events per genome per generation). Supportpersistence(new = persistence * old + draw) and keep the+=path when it is 1. -
Recombination:offspring(sire, dame, kid); column2lof the kid gets one of the sire’s alleles at locusl(0-based), column2l + 1one of the dam’s. -
Fitness:log_fitness(Z)for a traits x individuals matrix.
Random numbers
Use only R’s generator from C++ (R::unif_rand(), R::norm_rand(), R::rbinom(), rnorm_vec()), never <random> or Armadillo’s generator, so that set.seed() and seed = reproduce runs and a population continued over several evolve() calls matches a single call. Draw the random numbers in the same order on every code path you do not mean to change.
Adding a regime or a statistic
- A regime is an R constructor in
R/regimes.Rreturning anew_regime()list;resolve_regimes()turns it into the listevolve_cpp()reads (generations,selective,reset_theta,theta,delta_theta,omega, and regime-specific fields). Add the per-generation behaviour to the loop inevolve_cpp(). - A statistic recorded during the run goes into
Recordsinsrc/simulate.cpp(and intoappend_records()inR/evolve.Rso that continued runs keep it), with an accessor inR/accessors.R. Statistics of the current population that are expensive or optional (shuffles, mutational covariance, additive covariance) are better computed on demand fromgenomes(pop)in R or through a C++ helper.
Adding a component
Follow the README section “Extending evomod2”: derive a class in src/evomod.h, implement it in src/components.cpp, add a case to the matching make_*() factory, write the R constructor returning a list with a type (architectures also need loci, traits, state_rows, mutation_type), and test it against an explicit, slow R version of the same computation. New models are usually prototyped and cross-checked in EvoMod.jl first.
Build, test, document
Rscript -e 'Rcpp::compileAttributes(); roxygen2::roxygenise()' # after changing exports or docs
R CMD INSTALL --preclean .
Rscript -e 'devtools::test()'
R CMD build . && R CMD check --no-manual evomod2_*.tar.gz
Rscript -e 'pkgdown::build_site()' # website into docs/-
Time code only from clean builds.
devtools::test()andload_all()compile without optimisation and leave the objects insrc/; a laterR CMD INSTALL .without--precleanreuses them and runs about three times slower. Removesrc/*.oandsrc/*.soafter testing. - Keep existing behaviour bit-for-bit when adding options with defaults (seeded runs before and after the change must be identical); compilers may fuse multiply-adds, so keep the old arithmetic on the default path.
- Statistical tests: use enough replicates and tolerances that they do not fail by chance, and prefer exact expectations (identities, analytical equilibria) where they exist.
- Documentation is roxygen2 (markdown); do not edit
man/orNAMESPACEby hand. - Vignettes that run simulations must build in under a minute; heavy results go in
inst/extdata/with the script that produces them ininst/examples/.
Validation, CI and the website
-
validation/cross_check.R(against EvoMod.jl, additive and multilinear) andvalidation/cross_check_c.R(against the original C code, binary B) compare replicate means of G and trait means; run them after changes to the generation loop, mutation or the architectures they cover. - GitHub Actions runs
R CMD checkon macOS, Ubuntu and Windows for every push tomainand every pull request. - The website is built by pkgdown into
docs/and served by GitHub Pages frommain; rebuild it (pkgdown::build_site()) when documentation or vignettes change. Add new vignettes to_pkgdown.yml.