The {plant} package for R is an extensible framework for modelling size-, patch- and trait-structured demography. The {regnans} package extends {plant} to model community assembly and trait evolution, by repeatedly invading trait space, solving each community to demographic equilibrium, and following selection gradients to evolutionary attractors.
Status: under active development. The fitness and equilibrium machinery was recently moved out of {plant} into this package, so a compatible recent {plant} is required (see
.plant-interface-version). Developer notes and build/test commands live inAGENTS.md.
community_demography(), with fixed-point iteration, a Newton–Broyden solver that carries its Jacobian between solves, nleqslv/dfsane root-finding and a hybrid.community_fitness_landscape(), max_fitness(), viable trait bounds in any number of traits (community_viable_fitness()).community_fitness_gradient(), community_fitness_hessian() and the selection-gradient Jacobian, exact where a model provides them and finite differences otherwise, with harness_check_derivatives() to verify a provider.community_pip() (zero contours found by Newton, regions shaded), plot(type = "mip") and the trait-evolution plot community_tep().community_selection_gradient(), community_solve_singularity() (one resident or a coalition of several, any number of traits; Newton or a 1-D bracket), and community_classify_singularity() (CSS / branching point / repeller / Garden of Eden, with the branching direction and, for a coalition, protected coexistence).community_parameter_sensitivity() (how far a singular strategy or coalition moves per unit of each parameter, dx*/dp) and community_continue_singularity() (follows it along one parameter, marking where its classification changes); the parameter enters through a function p -> community, which community_parameter_map() builds for a reference model.community_canonical_equation(): every resident climbs its selection gradient at a speed set by mutation supply, stepped by odelia's RODAS; a resident at a fitness minimum branches after the waiting time for a mutant that can invade and coexist, immigrants arrive from a pool, extinctions are dropped, and the community and its fitness landscape can be rebuilt at any recorded time.assembler_run() with maximum-fitness or stochastic births, and inviable-strategy deaths.harness_plant() for the plant SCM, plus fast reference models with analytic answers (harness_dd99(), harness_gk98(), harness_gm99(), harness_jj12()) for learning the workflow and testing the algorithms.Worked examples are on the docs hub under Theory → Adaptive dynamics.
The aim is a reasonably comprehensive toolkit of adaptive-dynamics methods for numerically solved models, designed around the exact derivatives that plant is gaining through automatic differentiation. Next up:
plant exposes the Jacobians, so RODAS stops paying one equilibrium solve per unknown;∂f/∂n, and exact parameter sensitivities of attractors;ROADMAP.md has the full inventory with the status of every method, what the package needs from plant, and the order of work.
{regnans} is one of three companion repositories, with work coordinated
on a shared project board
("Plant model development"):
| Repository | Role |
|---|---|
| plant | Core C++/R model: size- and trait-structured demography, the SCM solver, and the physiological strategies (FF16, TF24, …). |
| regnans | Evolutionary community assembly on top of plant — invasion fitness, demographic equilibria, and selection gradients (this repo). |
| overstorey | The narrative documentation / field guide site (user guides, theory, worked reproductions). |
Issues from all three repositories feed into the project board, which is the single place to see what is planned, in progress, or done across the family.
Bug reports and feature requests are welcome via the GitHub issue tracker. New issues are automatically added to the project board with status Backlog.
To keep the board sortable, please:
Apply one type label — the three repositories share the same set:
bug — an existing feature not functioning as intendedtask — a discrete piece of work needed for a featureepic — a new feature or capability, usually an umbrella over several tasksPrefix the title with a theme tag in square brackets. Assembly work is
usually [evol assembly]; use another existing theme where it fits, or
[other]:
[TF24 hydraulics] · [TF24 allometry] · [TF24 nsc] · [acclimation] ·
[simplify interface] · [evol assembly] · [Env drivers] · [speed] ·
[patch variations] · [documentation] · [other]
Requirements
Option 1, using remotes::install_github
The {regnans} package can be installed direct from GitHub using the remotes package:
remotes::install_github("traitecoevo/regnans", dependencies=TRUE)
To install a specific (older) release, decide for the version number that you want to install in https://github.com/traitecoevo/regnans/releases e.g.
remotes::install_github("traitecoevo/regnans@v1.0.0", dependencies=TRUE)
with "v1.0.0" replaced by the appropriate version number.
Option 2, building from source
If familiar with git you might find it easiest to build regnans directly from the source code. This is most useful if developing new models or strategies, or to contribute new features.
First, clone the regnans repository
git clone https://github.com/traitecoevo/regnans
Open an R session in the folder, then to install dependencies run
devtools::install_deps()
Then to compile the project
devtools::install()
or
devtools::load_all()
regnans is part of the plant family of packages in the
traitecoevo org, built around the
plant forest model. Docs hub:
https://traitecoevo.github.io/overstorey/.
Contributing: please skim the family
issue guide
before filing — issues across the family are triaged on
board #5, and cross-package context lives in
plant-meta.