From 682b90be03a98f9e5a38ef3df679bd7986340599 Mon Sep 17 00:00:00 2001 From: Emily Dolson Date: Sun, 11 Jun 2023 21:21:17 -0400 Subject: [PATCH] Docs changes from #480 --- .github/workflows/CI.yml | 3 +- .readthedocs.yaml | 22 +++ .readthedocs.yml | 19 -- Dockerfile | 69 +++++--- doc/conf.py | 8 +- doc/library/Evolve/evolve.md | 38 ++++ doc/library/Evolve/systematics.md | 252 +++++++++++++++++++++++++++ doc/library/images/FullPhylogeny.png | Bin 0 -> 74439 bytes doc/library/images/phylogeny.jpg | Bin 0 -> 39648 bytes doc/library/index.md | 1 + doc/requirements.in | 16 +- doc/requirements.txt | 92 +++++----- include/emp/config/config.hpp | 2 + include/emp/matching/MatchBin.hpp | 3 +- 14 files changed, 421 insertions(+), 104 deletions(-) create mode 100644 .readthedocs.yaml delete mode 100644 .readthedocs.yml create mode 100644 doc/library/Evolve/evolve.md create mode 100644 doc/library/Evolve/systematics.md create mode 100644 doc/library/images/FullPhylogeny.png create mode 100644 doc/library/images/phylogeny.jpg diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index e8c7d0e902..e2eee81a06 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -7,6 +7,7 @@ on: - '**' schedule: - cron: '0 0 * * 0' + workflow_dispatch: jobs: tidy: name: Enforce Tidyness @@ -106,7 +107,7 @@ jobs: - uses: mmore500/actions-setup-docker@94429ebc8d9edb4e8c8afb2667bce1e89435f74f - run: docker build -t devosoft/empirical . - run: docker ps -a - - run: sudo docker run --name empirical devosoft/empirical /bin/bash -c "set -o pipefail && cd /opt/Empirical/doc && make html coverage | ./headtail.sh && python /opt/Empirical/doc/parse_documentation_coverage.py /opt/Empirical/doc/_build/doc-coverage.json >> /opt/Empirical/doc-coverage.json" + - run: sudo docker run --name empirical devosoft/empirical /bin/bash -c "set -o pipefail && cd /opt/Empirical/doc && make html coverage | ./headtail.sh && python3 /opt/Empirical/doc/parse_documentation_coverage.py /opt/Empirical/doc/_build/doc-coverage.json >> /opt/Empirical/doc-coverage.json" - run: sudo docker cp empirical:/opt/Empirical/doc-coverage.json . - uses: sylvanld/action-storage@v1 if: github.ref == 'refs/heads/master' diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..675e23b0d1 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.10" + + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: doc/conf.py + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: doc/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index e862e52db5..0000000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,19 +0,0 @@ -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -#Required -version: 2 - -# Build documentation in the docs/ directory with Sphinx -sphinx: - configuration: doc/conf.py - -# Optionally build your docs in additional formats such as PDF -formats: [] - -# Optionally set the version of Python and requirements required to build your docs -python: - version: 3.7 - install: - - requirements: doc/requirements.txt diff --git a/Dockerfile b/Dockerfile index a06368ac46..6879625359 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # Pull base image. -FROM ubuntu:bionic-20210416 +FROM ubuntu:focal-20230412 COPY . /opt/Empirical @@ -8,6 +8,7 @@ SHELL ["/bin/bash", "-c"] # Prevent interactive time zone config. # adapted from https://askubuntu.com/a/1013396 ENV DEBIAN_FRONTEND=noninteractive +ENV SPHINXBUILD="python3.10 -m sphinx" RUN \ echo 'Acquire::http::Timeout "60";' >> "/etc/apt/apt.conf.d/99timeout" \ @@ -31,22 +32,21 @@ RUN \ && \ rm -rf /var/lib/apt/lists/* \ && \ - find /etc/apt -type f -name '*.list' -exec sed -i 's/\(^deb.*-backports.*\)/#\1/; s/\(^deb.*-updates.*\)/#\1/; s/\(^deb.*-proposed.*\)/#\1/; s/\(^deb.*-security.*\)/#\1/' {} + \ - && \ apt-get update -y \ && \ - apt-get install -y software-properties-common=0.96.24.32.1 \ + apt-get install -y software-properties-common \ && \ add-apt-repository -y ppa:ubuntu-toolchain-r/test \ && \ + add-apt-repository -y ppa:deadsnakes/ppa \ + && \ apt-get update -y \ && \ apt-get install --no-install-recommends --allow-downgrades -y \ - dpkg-dev \ - libc6=2.27-3ubuntu1 \ - libc6-dev \ - libc6-dbg \ build-essential \ + dpkg-dev \ + g++-11 \ + libc6 \ xvfb \ x11vnc \ x11-xkb-utils \ @@ -60,21 +60,14 @@ RUN \ libnss3 \ lsb-release \ xdg-utils \ - g++-8=8-20180414-1ubuntu2 \ - gcc-8-base=8-20180414-1ubuntu2 \ - cpp-8=8-20180414-1ubuntu2 \ - gcc-8=8-20180414-1ubuntu2 \ - gcc-8-base=8-20180414-1ubuntu2 \ - libgcc-8-dev \ - libstdc++-8-dev \ cmake \ - python-virtualenv \ - python-pip-whl \ - python-pip \ - python-setuptools \ + python3-distutils \ python3-setuptools \ python3-virtualenv \ python3-pip \ + 'python3\.10' \ + 'python3\.10-distutils' \ + 'python3\.10-venv' \ nodejs \ npm \ tar \ @@ -84,7 +77,7 @@ RUN \ doxygen \ curl \ perl \ - perl-base=5.26.1-6 \ + perl-base \ git \ htop \ man \ @@ -162,12 +155,14 @@ ENV DISPLAY :99 RUN echo 'kernel.unprivileged_userns_clone=1' > /etc/sysctl.d/userns.conf RUN \ - update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-8 90 \ + update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 90 \ && \ npm install -g n \ && \ n 14.17 \ && \ + hash -r \ + && \ export python="/usr/bin/python3" \ && \ npm install source-map \ @@ -175,12 +170,32 @@ RUN \ echo "finalized set up dependency versions" RUN \ - pip install wheel==0.30.0 \ + curl -sS https://bootstrap.pypa.io/get-pip.py | python3 \ + && \ + curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10 \ + && \ + pip install --upgrade --force-reinstall pip virtualenv \ + && \ + pip3 install --upgrade --force-reinstall pip virtualenv \ + && \ + python3.10 -m pip install --upgrade --force-reinstall pip virtualenv \ && \ - pip3 install wheel==0.30.0 \ + python3 -m pip install --upgrade --force-reinstall pip virtualenv \ + && \ + pip install wheel==0.30.0 six==1.16.0 \ + && \ + pip3 install wheel==0.30.0 six==1.16.0 \ + && \ + python3.10 -m pip install wheel==0.30.0 six==1.16.0 \ + && \ + python3 -m pip install wheel==0.30.0 six==1.16.0 \ && \ pip3 install -r /opt/Empirical/doc/requirements.txt \ && \ + python3.10 -m pip install -r /opt/Empirical/doc/requirements.txt \ + && \ + python3 -m pip install -r /opt/Empirical/doc/requirements.txt \ + && \ echo "installed documentation build requirements" RUN \ @@ -190,13 +205,19 @@ RUN \ && \ git submodule init \ && \ - git submodule update -f \ + echo "nameserver 8.8.8.8" > /etc/resolv.conf \ + && \ + n=0; until [ $n -ge 3 ]; do git submodule update -f && break || ((n++)); sleep 5; done; if [ $n -eq 3 ]; then echo "Update failed after 3 attempts."; else echo "Update successful!"; fi \ && \ echo "initialized submodules" RUN \ cd /opt/Empirical \ && \ + curl -sS https://bootstrap.pypa.io/get-pip.py | python3 \ + && \ + python3 -m pip install virtualenv \ + && \ make install-test-dependencies \ && \ echo "installed test dependencies" diff --git a/doc/conf.py b/doc/conf.py index 93843550ce..baddcbfc42 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # Empirical documentation build configuration file, created by @@ -22,6 +22,7 @@ import sphinx_rtd_theme import subprocess import sys +import textwrap # -- General configuration --------------------------------------------- @@ -60,7 +61,10 @@ # TIP: if using the sphinx-bootstrap-theme, you need # "treeViewIsBootstrap": True, "exhaleExecutesDoxygen": True, - "exhaleDoxygenStdin": "INPUT = ../include" + "exhaleDoxygenStdin": textwrap.dedent(""" + INPUT = ../include + EXCLUDE_SYMBOLS += internal __impl_* *impl *IMPL *_IMPL_* *Impl + """) } # Tell sphinx what the primary language being documented is. diff --git a/doc/library/Evolve/evolve.md b/doc/library/Evolve/evolve.md new file mode 100644 index 0000000000..d0e2a65743 --- /dev/null +++ b/doc/library/Evolve/evolve.md @@ -0,0 +1,38 @@ +# Evolution tools + +## World + +```{eval-rst} +.. doxygenfile:: emp/Evolve/World.hpp + :project: Empirical + :no-link: +``` + +## Systematics Manager + +```{include} systematics.md +``` + +### Systematics API + +```{eval-rst} +.. doxygenfile:: emp/Evolve/Systematics.hpp + :project: Empirical + :no-link: +``` + +## NK + +```{eval-rst} +.. doxygenfile:: emp/Evolve/NK.hpp + :project: Empirical + :no-link: +``` + +## Selection + +```{eval-rst} +.. doxygenfile:: emp/Evolve/World_select.hpp + :project: Empirical + :no-link: +``` diff --git a/doc/library/Evolve/systematics.md b/doc/library/Evolve/systematics.md new file mode 100644 index 0000000000..354f5096c2 --- /dev/null +++ b/doc/library/Evolve/systematics.md @@ -0,0 +1,252 @@ + +The systematics manager tracks phylogenetic relationships among organisms within a digital +evolution system. For asexual systems, these relationships forma phylogenetic tree +(phylogeny). Systems with recombination (i.e. sexual reproduction systems) are not +yet supported. One of the major benefits of doing *in silico* evolution experiments (instead of or in addition to laboratory or field experiments) is that they allow perfect measurement of quantities that can only be inferred in nature. Once such property is the precise phylogeny (i.e. ancestry tree) of the population. + +![An example phylogeny](../images/phylogeny.jpg) + +At face value, measuring a phylogeny in *in silico* evolution may seem very straightforward: you just need to keep track of what gives birth to what. However, multiple aspects turn out to be non-trivial (see below). The Empirical systematics manager is designed to handle these challenges in a flexible way such that it can be easily plugged into any digital evolution system. It flexibly handle all aspects of recording phylogenies in *in silico* evolution. + +Note: A python wrapper for systematics manager exists in the form of the [Phylotrackpy library](https://phylotrackpy.readthedocs.io/en/latest/). + +### Features + +#### Flexible taxon definitions + +One of the central decisions when creating a phylogeny is choosing what the taxonomic units (i.e. the nodes in the tree) are. In a traditional phylogeny, these nodes are species. However, the concept of species is so murky that it is impossible to generically apply to computational evolution systems (we'd argue that it's questionable whether it could even be applied to biological data recorded at perfect temporal resolution, but that's a separate conversation). One alternative would be to make a phylogeny in which all nodes are individuals, but these trees are usually so large that they are impractical to work with. + +Increasingly, biologists have embraced the idea of building trees in which the taxonomic units are not species. Often, these are denoted by referring to them as an "X tree", where X is the taxonomic unit of interest. A traditional phylogeny, then, is a species tree. This terminology is particularly common in cancer evolution research, in which species trees are often contrasted with "clone trees" or "gene trees", in which the taxonomic units are genotypes. + +We can generalize this concept - any phylogeny of individuals can be abstracted by lumping individuals together based on a shared feature (see figure). This feature could be something simple like a phenotypic or genotypic trait, or it could be something more complex. For example, to approximate something more like a traditional biological species concept, you could choose to define an individual as being a member of a new taxonomic unit if it fails to produce successful offspring when recombined with an individual prototypical of its parent species (although note that the stochasticity inherent in this definition could have some unexpected side effects). The broader the grouping, the smaller the phylogeny will be (e.g. a genotype tree will be larger than a phenotype tree). + +![Illustration of different ways taxonomic units could be defined](https://raw.githubusercontent.com/emilydolson/interpreting_the_tape_of_life/master/figs/dolson.lineage_metrics_cartoon.png) +(Figure from "Quantifying the tape of life: Ancestry-based metrics provide insights and intuition about evolutionary dynamics" published in the proceedings of [ALIFE 2018](http://2018.alife.org/)) + +So how does the systematics manager handle this problem? By giving you the power to define taxonomic groupings however you want! When you construct a `Systematics` object, you give it a function that it can use to determine the taxonomic unit of an organism. Later, when organisms are born, you will pass them to the `Systematics` object and it will run that function on them. If the result matches the result of calling that function on the new organism's parent, then the organism will be considered to be part of the same taxonomic unit (taxon) as its parent. If the results do not match, the new organism will be considered to be the start of a new taxon descended from the parent's taxon. + +Note that multiple taxa may evolve that are the "same" (i.e. running the function on organisms in each yields the same result); each unique evolutionary origin will be counted as a distinct taxon. For example, let's imagine we are building a phylogeny of real animals in nature and grouping them into taxa based on whether they spend more than 50% of their lives in water. Fish and whales would be parts of two different taxa. Even though they both live their whole lives in the water, there would be a "land" taxon in between them on the line of descent. + +Example: + +```cpp +#include "Systematics.hpp" + +// Assuming that the org_t class has a member variable called genotype that stores +// its genotype, this will create a phylogeny based on genotypes +// The org_t template parameter is the type of the organisms living in your world. +// The info_t template parameter is the type of the piece of information you will +// return to indicate which organisms count as the same taxon. +// e.g. here, info_t should be whatever the type of org.genotype is. +sys = emp::Systematics sys([](const org_t & org){return org.genotype;}); +``` + +#### Pruning + +Phylogenies can get very large. So large that they can cause you program to exceed its available memory. To combat this problem, phylogenies can be "pruned" so they only contain extant (i.e. not extinct) taxa and their ancestors. If the `store_outside` variable for a systematics object is set to `False` (the default), this pruning will happen automatically. If you truly want to keep track of every taxon that ever existed, you can do so by setting `store_outside` to `True`. If you want to keep track of some historical data but can't afford the memory overhead of storing every taxon that ever existed, an intermediate options is to periodically print "snapshot" files containing all taxa currently in the phylogeny. + +#### Phylostatistics calculations + +Phylogenies are very information-dense data structures, but it can sometimes be hard to know how to usefully compare them. A variety of phylogenetic summary statistics (mostly based on topology) have been developed for the purpose of usefully making high-level comparisons. The systematics manager has many of these statistics built-in and can automatically output them. It can even keep running data (mean, variance, maximum, and minimum) on each statistic over time in a highly efficient format. + +Available statistics include: + +- Mean/max/min/sum/variance pairwise distance +- Colless-like index (a variant of the Colless index adjusted for trees with multifurcations) +- Sackin index +- Phylogenetic diversity + +#### Efficiency + +Tracking phylogenies can be computationally expensive. We have sought to keep the computational overhead as low as possible. + +We also provide the option to remove all taxa that died before a certain time point (the `remove_before` method). Use this with caution, as it will inhibit the use of many phylogenetic topology metrics. In extreme cases it may be necessary to keep your memory footprint sufficiently low, though. + +If you need substantially higher efficiency (in terms of time or memory) or are working in a distributed computing environment (where having a centralized phylogeny tracker can pose a large bottleneck), check out the [hstrat library](https://github.com/mmore500/hstrat), which lets you sacrifice some precision to achieve lower computational overhead. + +#### Flexible output options + +At any time, you can tell the systematics manager to print out the full contents of its current phylogeny in a "snapshot" file. These files will be formatted according to the [Artificial Life Phylogeny Data Standard format](https://alife-data-standards.github.io/alife-data-standards/phylogeny.html). By default they will contain the following columns for each taxon: 1) unique ID, 2) ancestor list, 3) origin time, and 4) destruction time. However, you can add additional columns with the `add_snapshot_fun` method. + +You can also print information on a single lineage. + +### Useful background information + +There are certain quirks associated with real-time phylogenies that you might not be used to thinking about if you're used to dealing with reconstructed phylogenies. Many of these discrepancies are the result of the very different temporal resolutions on which these types of phylogenies are measured, and the fact that the taxonomic units we work with are often at a finer resolution than species. We document some here so that they don't catch you off guard: + +- **Multifurcations are real**: In phylogenetic reconstructions, there is usually an assumption that any multifurcation/polytomy (i.e. a node that has more than two child nodes) is an artifact of having insufficient data. In real-time phylogenies, however, we often observe multifurcations that we know for sure actually happened. +- **Not all extant taxa are leaf nodes**: In phylogenetic reconstructions, there is usually an assumption that all extant (i.e. still living) taxa are leaf nodes in the phylogeny (i.e. none of them are parents/offspring of each other; similar taxa are descended from a shared common ancestor). In real-time phylogenies it is entirely possible that one taxon gives birth to something that we have defined as a different taxon and then continues to coexist with that child taxon. +- **Not all nodes are branch points**: In phylogenetic reconstructions, we only attempt to infer where branch points (i.e. common ancestors of multiple taxa) occurred. We do not try to infer how many taxa existed on a line of descent between a branch point and an extant taxa. In real-time phylogenies we observe exactly how many taxa exist on this line of descent and we keep a record of them. In practice there are often a lot of them, depending on you define your taxa. It is unclear whether we should include these non-branching nodes when calculating phylogenetic statistics (which is why the systematics manager lets you choose whether you want to). + +![An example of a full digital evolution phylogeny](images/FullPhylogeny.png) + +The above image represents an actual phylogeny measured from digital evolution. Each rectangle represents a different taxon. It's position along the x axis represents the span of time it existed for. Note that there are often sections along a single branch where multiple taxa coexisted for a period of time. Circles represent extant taxa at the end of this run. + +### Glossary + +Some useful terminology that might be useful in understanding the documentation (and especially the code base) for the systematics manager, particularly in light of the fact that different sub-fields of evolutionary biology tend to use different words in many of these contexts. + +- **Taxon**: a generic word for a specific taxonomic unit. We use "taxon" as a generic term to represent a node in a phylogeny. For example, species are a common type of taxon to use when depicting portions of the phylogeny of life on earth. However, sometimes people choose to use higher-order types of taxa (e.g. genus, family, order, class, etc.) when they are trying to depict a larger swath of the whole phylogeny. +- **Taxa**: Plural of taxon. +- **Multifurcation/polytomy**: A node in a phylogeny that has more than two child nodes +- **Bifurcation**: A node in a phylogeny that has exactly two child nodes. +- **Non-branch node**: A node in a phylogeny with only one child node. +- **Leaf node**: A node in a phylogeny with no children. +- **Most Recent Common Ancestor (MRCA)**: The most recent node in a phylogeny that is a common ancestor of all nodes associated with extant taxa. If the phylogeny is pruned, there won't be any branch points before the MRCA (because any branches not leading to the MRCA would lead to taxa that are now extinct). +- **Coalescence events**: Occur when the most recent common ancestor changes (i.e. all descendants from one side of the deepest branch of the phylogeny have gone extinct). In the absence of diversity-preserving features coalescence events are expected to occur by chance with a frequency dependent on population size and spatial structure (but be careful of distributional assumptions). Observing coalescence less frequently than you would expect by chance can be an indication that ecological interactions are present (we have discussed this more [here](https://direct.mit.edu/artl/article/26/1/58/93272/Interpreting-the-Tape-of-Life-Ancestry-Based) and [here](https://direct.mit.edu/artl/article/25/1/50/2915/The-MODES-Toolbox-Measurements-of-Open-Ended)). + +### Quickstart + +#### Installation + +The Systematics manager is part of Empirical. Because Empirical is header-only, you can include whichever parts of it you want. To just use the Systematics manager, you just need to include the Systematics.hpp header. Note that the Systematics manager depends on the result of Empirical, so you will need to download the entire library. Currently, we recommend using the mabe-systematics branch: + +```bash +git clone --recursive git@github.com:devosoft/Empirical.git +cd Empirical +git checkout mabe-systematics +``` + +Then in your C++ file: + +```cpp +#include "Evolve/Systematics.hpp" +``` + +To compile your code using the systematics manager, you will need to tell you compiler where to find Systematics.hpp with the `-I` flag (the below assumes you are compiling from the directory you cloned Empirical into; if you aren't, you will need to include the full path to Empirical): + +```bash +g++ -IEmpirical/include/emp my_source_file.cc +``` + +#### Usage + +##### Creating a systematics object + +The first step in tracking a phylogeny with the systematics manager is to make a systematics object. The most important decision to make at this point is how to define taxa in your phylogeny (for more information, see the "flexible taxon definition" section under "features"). You can do so by passing a function to the systematics constructor which takes an organism object and returns a string that specifies a taxon. + +For example, to build a phylogeny based on genotypes, you could do the following: + +```cpp +#include "Evolve/Systematics.hpp" + +struct MyOrg { + std::string genotype; +}; + +// The first template argument is the type of your organisms +// The second template argument is the type of the piece of information you +// are using to differentiate taxa (here its a string because the genotype +// member variable of our organism struct is a string) +sys = emp::Systematics sys([](const MyOrg & org){return org.genotype;}); +``` + +There are a couple of other decisions that you also need to make at this point. The first is which set of taxa to store in the systematics manager. The defaults here are most likely what you want to use, but in case they aren't, the systematics manager can be told to store or not store the following sets of taxa: + +- **active**: the taxa that still currently have living members. You almost certainly want to store these (without them you don't really have a phylogeny), but can technically disable them by setting the `store_active` keyword argument in the constructor to false. +- **ancestors**: the taxa that are ancestors of active taxa. You almost certainly want to store these too (without them you don't really have a phylogeny), but can technically disable them by setting the `store_ancestors` keyword argument in the constructor to false. +- **outside**: the taxa that are not in either of the other two groups (i.e. taxa that have gone extinct and all of their ancestors have gone extinct). If you store these, your phylogeny will get very large very fast, so doing so is generally not recommended. It is occasionally useful, though, so you can enable storing these taxa by setting the `store_all` keyword argument in the constructor to true. + +The second decision is slightly trickier. Once you start adding organisms to the systematics manager, it will create `Taxon` objects associated with each one to keep track of which taxon it is part of. You will need to use these taxon objects when adding future organisms, to specify which taxon their parent was part of. If you have control over your organism class, it is likely that the easiest option is to add a `self.taxon` attribute and store the taxon there. However, if you cannot add arbitrary data to your organism class, keeping track of taxon objects can get annoying. For this reason, the systematics manager gives you the option of letting it manage them. To do so, it needs a way to map individuals to taxa (since its possible there are duplicate taxa, simply running the organism to taxon function again won't work). It achieves this mapping by keeping track of each organism's position in the population. Thus, to have the systematics manager keep track of taxon objects itself, you must set the `store_pos` keyword argument in the constructor to true. You must also use the position-based versions of add_org and remove_org, and make sure to notify the systematics manager if any organism ever changes position during its lifetime for any reason. + +Once you have created the systematics object, you just need to do two things: 1) notify it when something is born, and 2) notify it when something dies. + +##### Notifying the systematics object of births + +You must notify the systematics manager of births using the `add_org` family of functions. These functions require that you provide the newly born organism as well as either the taxon object of its parent or the position of its parent (if the systematics manager is tracking positions). + +Example of tracking taxa as object attributes (assume we're building on our example above, and already have created a systematics manager called `sys`): + +```cpp +// Do whatever you would normally do to create your first organism +// Here, we're assuming we can just call a constructor called Organism() +MyOrg my_org; + +// Notify systematics manager of this organism's birth +// This is the first org, so it doesn't have a parent +// so we do not pass a second argument/ +// add_org will return a pointer to this organism's taxon object, which we +// store for future reference +emp::Ptr > taxon = sys.AddOrg(my_org); + +// Assume stuff happens here that leads to my_org having offspring +// Here, we'll pretend that our organism class has a Reproduce method that +// returns a new offspring organism. You should handle this however you +// normally would +MyOrg org_2 = my_org.Reproduce(); + +// Notify the systematics manager of org_2's birth. Since it has a parent, +// we pass the taxon of that parent in as the second argument +sys.AddOrg(org_2, taxon) + +``` + +An example of tracking positions is coming soon. For now, feel free to contact us with questions! + +#### Notifying the systematics object of deaths + +You must notify the systematics manager of deaths using the `remove_org` family of functions. + +As an example (again, building on the previous examples): + +```cpp +// Assume stuff happens that causes my_org to die + +// We notify the systematics manager that this has happened by calling remove_org +// Note that remove_org takes the taxon of the dead organism as an argument, not +// the organism itself +sys.remove_org(taxon) + +``` + +#### Taxon properties + +Taxon objects maintain the following information: + +- taxon ID# ``GetID()`` +- details of organisms in the taxon ``GetInfo()`` +- pointer to the parent group (will return a null pointer if the species was injected) ``GetParent()`` +- how many organisms currently exist in the group and how many total organisms have ever existed in the group ``GetNumOrgs()`` or ``GetTotOrgs()`` +- how many direct offspring groups exist from this group and how many total extant offspring that exist from this taxa ``GetTotalOffspring()`` +- how deep in the tree the node you are examining is ``GetDepth()`` +- when did this taxon first appear in the population ``GetOriginationTime()`` +- when did the taxon leave the population ``GetDestructionTime()`` + +#### Systematics manager properties + +A systematics manager object maintains the following information: + +- Are we tracking a synchronous population? ``GetTrackSynchronous()`` ``SetTrackSynchronous()`` +- Are we storing all taxa that are still alive in the population? ``GetStoreActive()`` ``SetStoreActive()`` +- Are we storing all taxa that are ancestors of the living organisms in the population? ``GetStoreAncestors()`` ``SetStoreAncestors()`` +- Are we storing all taxa that have died out, as have all of their descendants? ``GetStoreOutside()`` ``SetStoreOutside()`` +- Are we storing any taxa types that have died out? ``GetArchive()`` ``SetArchive()`` +- Are we storing the positions of taxa? ``GetStorePosition()`` ``SetStorePosition()`` +- How many living organisms are currently being tracked? ``GetTotalOrgs()`` +- How many independent trees are being tracked? ``GetNumRoots()`` +- What ID will the next taxon have? ``GetNextID()`` +- What is the average phylogenetic depth of organisms in the population? ``GetAveDepth()`` +- To find the most recent common ancestor (MRCA) use ``GetMRCA()`` or ``GetMRCADepth()`` to find the distance to the MRCA. + +#### Phylogeny metrics + +Many different metrics can be used to quantify th topology of a phylogeny. For more information, see (Winters et al., 2013; Tucker et al. 2017). + +The Empirical systematics manager can calculate + +- Phylogenetic diversity (Faith, 1992) +- Taxon Distinctiveness (From Vane-Wright et al., 1991) +- Evolutionary Distinctiveness (Isaac, 2007) (mean, sum, and variance) +- Mean pairwise distance (Webb and Losos, 2000), which is equivalent to Average Taxonomic Diversity (Warwick and Clark, 1998, Tucker et al., 2016) +- Sum pairwise distance +- Variance pairwise distance +- Out-degree distribution +- Average origination time +- Colless-like Index (Mir, 2018, PLoS One) +- Sackin Index (Sackin, 1972; reviewed in Shao, 1990) +- Depth of most recent common ancestor +- Phenotypic volatility (Dolson et al., 2019) +- Unique taxa on lineage (Dolson et al., 2019) +- Mutation count along lineage (Dolson et al., 2019) +- Tree size +- Maximum depth diff --git a/doc/library/images/FullPhylogeny.png b/doc/library/images/FullPhylogeny.png new file mode 100644 index 0000000000000000000000000000000000000000..af33ec5f4751a8a4d49b8d5a0ca4b7babf15d181 GIT binary patch literal 74439 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

LLvJV<>ugp!{DYy{7b;a?2+wq~u{ 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

-;@a|~ltLPBtTJVCu(!dKD?qC= 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�hTg{KCotvuZ;@-I3Hg-wV!cKFU~sCGvhHN9=QAY%m#-^N?kp#atjkzb%@nMMPeE_hwyr_%Q)Me+RF@ z^O3m5;HHYCwh;;A>w?p`Oci(ZUv)a=yO^)JvA?DF<yo1QC;Oy3$Gr9*k{UzC3t+>F z$kX;?O=1x2dOUVhiXeA*?N^LXCVDj1>3626qA5eNZjJLo%4?dOgM(ZHjVM*ONCk8r_jQf~Hr%Jo10x>b zkt#z`o5@M){9s=^-`q%$uxag(-@~XXFK=)VWoxi7fp(jTNyeu&7zHq|AVM{- zALgL^LKS6M;Qzm0v3uxE5pbiugbe|TIhs-QjdvF-Iq-&3{rpa7kL9SIoABJ&w_E|H z6>J_{p0nz^M;SmH24Op;5Ekh@b^U5(nxx#@v#hUt z|C|xeoQ<4l6dzZJha0NW#7O>qXP+dfiBt$9W^g@HY5_E42v^A&ra2^=41Qe8X{IFikY!xTt4qBeljzbumoJ+W zA%HdN^EO!YtU zu3Ria%V3R&9mQ!kK#Nv#mCQ+jYYZH5d2^Wa+$q{CKR=F*ZaV z7ppdO(fhk=m)JUHJo^_vx@ZS9a2lg}n z?e7kd-$1$xe9QbDCA@~)m(DU=Iy)SAC3CV^lauz~{mSo9(QF;gZzu!~D0JI`lY$^-Bj$RHd9~l!IoJ!mAd5-R5&uV5kZXAQHNaCO1 zN9E3-{WfwEuYg+c->|gkIY=yILZ?7_=rtv8J-^Y}k@pu&mi?9LKEFTR^~!SPoR63= z2H7%*6uqL#VZl!0nd_q?ytE==r!T{6MrX=?x+cA2%|tnFCU9hwH&nXQ%tLP{%J*@C zX)R*g9)B=Tk+xd$Xw~8=U)dCZ7Z0PibX{U%~wG;*BZ9+EafS?$@zps$y>=Qh9W z3T@P7U0Fnwgm~3`)@wC<8|J80kjqg2eYH|^*9493S>cZC7SJzkH)RrC8Yg3Q%)Mji z0_QeGaD`Td-VeM(Ife~=o9@NU`&@Olfm_?1PG82*FnTL#QS%90P-4rCKdMN$#&*T zF2XmiXdAIFGfVOo2J(fJ&Sq53u2r~57?W?$ViwA$9ChB@=}iu(5y%lRE#9>; z&)K=`8@mL3>EFIRksMo_R(5A4SN*1a$hw-{cqW~r=_8d+hP$V_`p5nI)enm2=X1Jt z=i1p9Td+HVi_gz57}f72gVLRys)Ksqr!W6rps%r&x81ZR#h#bCL)HEs;a-FCRBz{F zz5I!puKmyRp$i(L+G}f^Hg(BiE%h3G+rMW+LA6-7TyIn&4X2oPe6U!6;8WJlWpnH0 z-TI1h;e%g|K>~OF20C~RC8P%Gp{#g#C(0xrK2QN2UW;=&-S(y-Bcm6H)Ft^hYlbfZk8q$OX2McQt;>a3wS;Cb5a90l)1g@W-(QO7E1(&8zk%RyN(c{_;QIBy zf7x*Ue%s&wXdrGvU4Acv{`6(_HuiF%$!_w0XTxL0V|@AdGa4uU#w5^+g8w&+_WLV4G;hC^T5l)`@8(W;QaqOK?C-T4#)NtWz$<+xU))1$UQ6& IGkEcT06ndyd;kCd literal 0 HcmV?d00001 diff --git a/doc/library/images/phylogeny.jpg b/doc/library/images/phylogeny.jpg new file mode 100644 index 0000000000000000000000000000000000000000..3652ff4d6abfb6a00d514ab812f97ecdddf99aea GIT binary patch literal 39648 zcmeFZ2|QGN-#)hbDf7_!V&D%q1nmN{)GWI`xpvL%VhF3U{z z5VG$LgY22Hj#73ty-~qqE z+YyNK!ibgJ*I+}O7y0cq_usb8E>2gK+-z=Mz3S|C-Q^bejVS@*McAZHS2}etzFN3&HWJW?%ch=-?gjx zS99O-ul;a7B7|43h*%N9%d;J^LYRkFn1@q=K!P*j1J{9jDgN@qvx0Xe-zsoO0)pTT zxf{UY^YX3$2g|n-oH&m!_ttcp4sotOBkHj3NQyN`MKxC zv%&*xyuvH_w(VOba^yV!C0Ehy`|qt5I~p3FS-M76)rcy7`DT;AM!5q6J80Zf`*CLf z+=<=)x6bUZC-&QUbtBgD@_@EOW^TS-xG~f1Mn{;ezU&zh@!-hL8(5>G)v<%GQLHP|Y&4FQcAkS+*~vkK zQ>Yl`BAIc_6_YN`L<-wp*sst^J?L{_hs=ffw(o5j-@o>mv&u`gl!7ReN{&6!A*pMa zx*HR(yiAnvR@^~z47-R7;~;3^qI!WIEeW*hTl1eyS`DZBP7NP zQzi$|kN=Y$#Qx^}NZKk6V*IMbGzW1XtIt7Ho#i0fJUNKkT;#9cg-I7X50f~E)*YxK z7y(sCaS*8yE+lx(k_rbQsmVc@3~~?(tJhK`O}aGi`NnL z0Iq#!&p}*o_es~pcx(2!(bC}knnGU@7df-$^3iv3eFlhlti zgcHDVn;1@f!>axECLFy^h*1Es-k~Sc#h?l!4&u#bj0X!G?|EokA!U9RwV5=y2Q@yx zLCj?8vaSZOEm5$k;(}=)in1GOU8lmm3~xyD;>L_6{1Xf<5;=c^gIF?4{Ob{kGZjxD zX=0@DRZ)E$1OnBHVFaeKeHyC>zkW3c3&~3y1X_rLhzMjyB;e?Qn0a1(?i3=&RoEvk zz(m_YnUqwxZL@NW>zzBU%%3ircOP#t)M~b;Rj;*QV|z_Y;qDqaDuR$s>JKO9TW8X4 zdqe(S^BKu$_FhhYUsF^b5#|Gm;zoVrZ&!U9wHOxhTlvZJNVS&lB_^2YngZ5O97LuI zIFM#@#aRrz8qYz<`$8PV<-QI$B%fgS&C_|?z~r^<#LZ&ECmXc#FLq5N6Gz;K?%>Z8 z!bdjQA4ofW`ZX@bN;zj@@jI4q{)9N)j`8&T2{FX~^2Wmr#6K*ur4wMV-@g)aBCUGv zto+qru@jwVVhsDalJCGKj3P|D=dkocVNNCm5Oo@L(>EfV$!0JgJ^1>XPp11u6g@G6s+gd z(u6%jU%#D$2>s6A2HTF$i=D@W_$OFST{FQVXvOB&X+YqO7K3{2|{`lHhA^Lpy2SS4oefxKuI-Y4s z*23A>`W(8oPx|vsPDATVB|lCld_I ziU>m37ScMF*#)~e6xC{WZ^I||G+WnFtv5a)JpCbUl*{`q%K~U`&g#4mV>OL6eSYr_ z`I+vY3xiU7o6dFGn=+DQoYE^agl(lLHzx3JQqw-$rCjr{X1w|nr176Xp}aE~cugkA z?v?$d#c9%*pE2zQSJd8}bPUK{bQ!Vt8K{~g*rVj|K$FR2(v=M;Kq>G(uQXOx@`ALQxkJ$>qYBb zy;>5Qr&Zjs>ZIBcE3I{2F}l-V*j5>~6vHYUKWj@1v4cVu^MuOPhdmU>y&jszS2Hy` zops9PItCg@90cDQb}GqX%E&-NmnQKW5146bFO-)|7wf;}i(q$&e#WDww-OR?E1Jrc9UCPCu=;3v&x|c*!SPbM zT@v=8k0Xf6Ngn~ag;>+|LjTOc^rKpDE0eko+;HX~?CtWD$qP?WgBWq_7Zmk|L?!O= zzFu>>ihdIoIX1f@?SKP2{>?5eDE;Z`YMIa#nwuA0?jxzrw*GVYog)+^PR-!jS;@&9 zP4{d+!^JbrF1DB(kFXI75+8ANd5==4tMHo?L4eMGBEL1AYJ9HPlvsQco~he+`zX}e zt^GDJc)+oUE;jrqdP0dLrNW8`$SF0V8;8%rq+>JagK)chC-m>AATf-|agzdu<6jwq!F^jGiETH0-n)$e(0Ww+jVCLjjIzPC}oVC&t>+ z2aCduKWtqU=Tw(NMDQZ`03{Zmm_t8!>3U6LuPcr^Abr6mIX#5k=X^{25`LR%y{>cNY-g;-SEzJ9>ADb)rEf+{nMTZ@ zr07^-ZuY5tvo}Pn*a6P3Y@)AtK~o0QyEtW3aJSFCEtgUGhK~E@`j9Sl-J~m{1bujW z!~VBuE)LGDUd1SpIWYd+cY6}mi9Wl3bX51$XGM!tHdh_0I^2Dlal4K5 zg=sM`QehxLseZ6W>)1fwQL;(X{6SWo!*j#hev#E9PfPEu+_K@w$`y+CL_k39tBo7m zqp}RhF|I2o_#ZhZ;%b6wL)2zoIr0g-^7&kyV&pKfnN_D#mw5NH;?I=t@jJu4dy-j= zd9|51i3cfV-!x=8)72!MKH3tQd7~+?R)*%i zX!g&9nrZsZg+w_HB5(SENhIJozMaB`tUHz-ylRYc06-&NU;Q=N68TOqt#fi=jzME$ zWr4d0jfUO#19!bz@w-hZ77)7xB=tPB4qGa-B0p@L%yg+_P*4jxA-Ej9d_=t}v{K;| z@~c}}h-B1^VI>E#iFAFMt}qfJ*PPyAO*1IIsmMXtjGgz5(rvkkJsBRlxqn3D>~N8D zdLvySFNZ9J>VHjCXr3laD}6rf7kTeG@l>RyS^L58`<7cIJe~%-yJ2$4ygGbz%z`W3 z_BCCOiH1n_s6otsAMBmMTwnE?0jsK=-ToC{ypcYxTRs zmuy_&rs)OwQUYC$A3zl9rAuMR72WhO#-3{v6(V^FSE}C`GI6#0Fb3x_vd>+wIRv?M zo7&yR6_VD$9tZ7h(ptY_Zu_YS(Ou3`BO|0kB2v2SBKHRCy4bBK7lTfmL$LU)5(1Y- zcJ_6B0uXzvz^;V5f49*|u%Ne-GsJCK8rIxv7=5GNAR%Qi1I2 zgk=Ytv;cz$eTiZ$kmgd6kLiH#Zr@CvXJ8m7_9g@>&So!sO!%Yr#!K~B_*RsSp({)W znhccKkp@(9r6R{nRG+)fOv+R1u{3o5^iEX#Q}MaK+Q!`z}(JL)+)e@qm6MC(l0anfjhI2 zhoCFIKb2)AfX~o#uL$EujVl%1MMe0!W43ZBB5CMLt`JkwnKXAI*VotFHSfj3Zpb(K zMk6cm4de%i5@wHg{C}8}@DB^IL?0X_=CJcvQgV47=c@?5QJ&@(pm^C62ceu$xH2$O1RVvhz4I8yk2+S=`s913(8FL?*Z_7$fsl+TC z?1m01E)q${2XTvM_}SjfSa?y~g_oJ~W8qzD zz}C5TzK7ixB76Y5;Vag^gR(^l`o1-f2aD) z=t>mTlC-2gEdZ!!EuNw8ig7?!VyKpPQx;sP8I*EZ;lijY2ceuVKFmyWpLCc8Ly?GBrLt9|S^+j5IM?J|yafUWUA&117X_yD3 zd}We0i6!n2uYpnJR|gD6~4fg8ve2h8*zL7 zd==v9${1FRhaWU~)sVfTfRLL;`TY=~AGx$^FNwmIoGms7Wgrm7zg0)|KPJyyzZk#{ z&c`secN2+(r_k?*-W8Bx-A)26`|KvLR854afIKS>8+!iP(fm)1vp|x&?>yGA0q*&_ z*7p9@bBkSj9`XPI5%bPuS;>)se2j)$QlON2?*h+z1?iePcb+~ou?!gp~8 zG*(3+nLGT6-a-0J?uc6n{Z8$8w_GH#Hn59O!%8{|AlX#4ER|wP=II(tH@o-XqVieM z&OCWzUIid(R5yNiq!s(p;6ug6cG4ZiIb{uK^4FY*{52=W{Z}~=qFUZr3uQxouKDoE z3*)aih`RLZbl+5r7|7?K;12Z^D*`C50F5bC`a(QV&5>UK=1WTBk{B8Q%xo@~eOklZ zHokHStenV+SG=&9g%`Rbmzx~_&rDeuxLgLfB^?z2eM!C`A~nPrO_&H2^{jcaOOHiq zPp)5q)#8Uo2dX_7;?;}Kgg$qS=VJXRX9#~I-{;?R%{yTZwQxZQ`{*wO3jF#bfhr~R z;E$EyVF425MPhcLCp54(SLbp?<&Cw64pk{GMv_)T&f31|00ySX?9QKc-+=^knbBI* zgWQQ6=xOOuW0qjzU31~oyCfD9z!Z=m{{mAQ4gaMCIf$YwMTK(^Yo`Yw&B+*OK=zDp zVto%j+pwi>1Z91giSD=|l?VAjUqQxXnG&9LSYzI*K)(l$m>nP*Bz^GoEA_`}n97ax zQ{PF0zh&cn zL38VXUN#`d`(kOBx9&?Q5T0MNLR5M@O5f#2&TLpDD+JVV5JwB<&neE|Cmo^5o~Z@0 zx0TXD5_Vs|1M!3fOwvz>D}NA&!G#;kV0d2Yu?0X7pXJcg;A$zu5kBnVa%r>a;2^sN z^d+r1h*NPHSE)vG9K_Zibfot0Xy4z`KzcST7~tH2$`0@|Ib#C|;Os%nl6%4Yc4Eu2 zq<}Q^s*HmOnzLhj3DR!j*f^wS&`6> z9Ew@{8&awM48A9!af<1|vNxmJ<{@G{HF7*PZ-Xsg zMt*yi+K|+C*nY;jMybbJ4r>nm0cE1#k6#bB6t81i(dE%?%Cfnc%rox~WU03WH@fWE zWj4oqD=5r!1?gwSIg|*6gUGQnOnjX?_l#8UJ2C+CF<1`Gl$?13Px z(uCKn#Lw&^j4={z;MD+B?DTsBb=HB7OM+6`#P|~bGJ|zbKz{fAh1=tPI5!k&T)7)UmzdDcy zub~oCDUwkN%JXaZp5!xY6K@4;Ki`%ysc!L@z}lr=G)Y{HpL>DgA32m9$1k*7ej)uj z$f!nHEW;0J64glIVidLUlm@)LFY@{>RZHwZa_)&x5~D27~B{G|H_CO@pFHgExr4eY?o%ul0z+F?6Yqutr`~GL9HIB zFJ6Ep431SX60RCgesXer0OcNdAm^R1S0|S`U5UbxH$nZ0paw;XA< z*=>96@EWj7%Epl94gRKEoNqH5$W!~|zvhH!s+2lB3<6r;iz&9( zj&XNm3RZNWsBT*VO`LHdHEXWWkb~d}b|yA0wSkMZMt0D}AL6^!XK|K@tLSDIU!Av7 zXhuaN?yTsYkGb9-yaIYC6Tv@O50-)|EoBnU9M##GA5(c)`o+vj4Wmtj$rZHRD_g@P zm?7);BCf6=ol~sAqOcXvdf>R|k}K>u0A)>xD3hlQwBbgNNwfZU&&QaRj_V^PfA%a3 z*^X!xI(zNvD95X_A6?cF7*=vKt zEMbtJCEQYZk+;sZzr@>+w(fn6g?`h5X8dUUhbOoXyXOef56;oYm{RpQ8o|Z#4uUr_ zo+!uG$9?p_2a4=`MnKsiYt+};eWwAAQsN+V!RjO#m*XB=9tkI&-BFiZOBx>5CTVQs zAg1O=vBl>xv3NmJex=p?y_VKQnH#>YM=SB13;bmnAMZU|5m8 zMI$=7!_Ot@<4mrnPr)o%bldfhiMUvb$r#b*aT*EXd* zIv37VT||Cmcg%$AJWhB!+TDkLH22Bn7PHP`Li1kX?x|t(%TK-1c5j8n?TMH5Qm*+< zUP=0p_!eZp&?A2lhWM8u1!b6?fD@T9us|y1MN&!hAs|mE=jxb+hs_2hW!u^4PCK&+-18K2v2wqIC+3#8R_?42`veS`5+7Syv6w}L)j zEm+!KD!DaVU>>3?qi|~aH7wEo31klYUSbTo_&76M=lHo1cCP^k;mbs)LZw_Bk6X{$ zMOR9okAH7aoZjRa-7|%8c)=@un7^Sj0a27uB64mKR z&mEk4mKEW3q!zSs$R+4#xVxC}4JL0m!#2c;J-`kCr(`jGe3Amyt}>7zbD z4x(^S_6xe5oVmyn-(OCNOS2sy$&@-IOhlc1-#xzfsv}_wRlHQLVra3($dF1E>bOY6 z*-_T*_f}+Dcu#01?W^ajxO^(vxOM;gtvDM@G?{8d=p^XV*JO+l<*3g@j>J#QYKe@E zOSV_t(C`TeA1tQK7G)ap^89P%~XmlSVKxa~UL%!CbcSTAvPZfB(%3bqTW z*6drKu~EsbIWEtjd%W9uF)-+&m73dJRUnmXz4NHl)~AprGvj+5g!XjDh0WNx)hYYb z96x@?v1=$lvL?*ysiD`R0INs(VVs1p)`7(b4&TSIBhRi~m|ZKr$9>23*1#}BcXw}; z+Iyfe)Ou|LDTu$HJoR}2tcLk%vG0Y&=BNRcoTZH$(1!wuG*;ST7>OU{>>_Lrk_^>^ zEY?%)dqM^4korSPrnlhFIK>c^3&F%hr#gnZJabBPO@beH$pDhuoK z)@+hqiDOb_D(Hw-F zx;YFiKlyRlC&bY8$S2DxDn8!e;zon&C_Df$g@oAh(Zn(W4(iXw%pBDMi|o<>py;#c z<{JM6q|HBCHI$dZE? zEl?b{uM32RTpn={qKCD#!8f@8=5I{_`P`Ggi+fC5K};nQn@!T%0>!FhJ5!`{)hE22XGDE=Y%XScv1^%V_H2QuSVL3aJf0_>}u3mQiQJuPi+?r znn2!w;L(hT##VQ*Z$1D>3fkACz?Tz(K zRz?l`k!V|asf2Vz8TE)C^!&g;gyY-$@HohW|A8i+&}S4~Ie-;~TLtC@!9k22k61)b z$^tgxLhXP*ZX`4Kd;nD7`vT^J)=y?4knCMy#6k8$Xs90E4E9;k!$JH+c>NhQWOA&7 z)z}59`6)*N3m{P!?Q38?yg*4V$IArhi?E;?h&@?AhZkg!3_~?vKa31W*4Icw4?Qt( zc{#B8eIq3G0}t(%FY|0kDsd-Nvo9F5GXcE{;G!CX7w_jA;h_7(*Mvx@|0#aP z-UGED1BRP!pj+FbfGYNhEDZ0wXeYYKBsEyf{Eae{ErS z|JuR;EvMzW73fb8^@QF=Oqb|6#m&_mgt$_NU@Y_|Z+<7S_+7y-N$Kx(aonxtRLlR) z7z>Cp_Xq9rCCJh&nM?W6KNqf9nXs{%aXcKId+rGYjzwOZ9FF1u1Xf=Xsd z9E0_%A3&1`XfEM26Sp7?CQyS87S+#!F6{E35M!` z&lwQMHj>;Wnk?%EuUP{EJ;e=VuL(R`g3s3gvj+sjHq=n-cW6=@j3@LHQqz{O_0Y#+ddNotnou&SM2ROzv6YC z-#2uZ6?4;<9fiQE{e#AvxopmPu-xcXpi9r_R6FIl3wv08_Xq_)|HJN$YuL#sKNF*J8N10}&0Z+Jf z$}w;mqw*{ayKat|9K}ubgx@<1Ap4#Hc*h`>km4{5aP_STSLPn8{pDK(*(Gi>@t09; zEHqwMZ9K*s;#^iyALLOp zWn7FD3iSt03&Nke1H!k2g06d%rDnh((Ek2ma4>hxXW=q2gV$nJL8I?2asY%sx=v>F z&-%ar<~Yw%z&|cnk5K&|OzTnA5WmyD;Op|!r@+*zhb&8` z5})e|0L#J)Oc+x`oJ23pBGFLn;`u;Oj<2w;ESEtQhg9f$+-ong)=`V}T-JR&JSuf% z4_KwTQTS&MFxDNPFjTXNXSsB#f!kqUrS7_aQU7Gd1LIUsyH^pzL1A@0)-h*WPLBW) z-k{1-1TlAVnkAw$;0#?2iaceLkC~bX&Dvi9r3El6@a@D`geX#f=%Sz-H{y;-1BBsX z`6M(_5!?ndEdpI+_-9gZOH!9n6%9BcARoqpY}io%){6C-1#aG1PAe$I^t`Si!vZyw zsJ``N`WdD5Yu^f)Y1*nW+c5F8YUXQRxC9Q>wyf??9)r2FI1=z|x%|u>6Q>!nBvfF7 zqB7FL{uDT@7v0@Pb74uW;wxas7AvG5xFJN>+wlEH#Sh=qIRg-Kb`_g2G;HwFcaV)k zPe6ukoAK1+(@O`Gj=@zH1hz2f*P}m?s3$y4g}S89nM5B70FkD9b5%7X$YmPgF!8ny zSfKtWlbS6a{ikHlKM{GC*;nXuBVBo8nlhf&Q#!G^M}2B#__v;FP%dzf4{tQal@a^c ze#3Tv#ghZp_Z(CAb3EH7pfmmRLF5q(n2J)@uYB}r0B{Z;N9x$ia#KGtcf_BI2=L-pF36k4pgF9+rdlAW#?t!)cdqS zGJQ`6>nTnUU^h=_Osj1!76~#^vRri@s0 zcbZM|%bx|o1%p;?sDbwa`#c1%ewRs@40?0NK$gJGS%rLDQ`VJ^4)+-hOE_+h4A&Gs z^dBFeg%vbIzgezDF@mrwYdI&GkN{lT~hy4QVT%!7b0h@ zwWI)|;sppt1l0!%)dWz=kG^^Qz^evuXA z{O-f&gG>1j80hI8zxVw81;GDTp1(hO`r4Oi>5=Y2zqa%mXn$$xbpjysJFRkg{SsP2 zUM5x5AN)-|i1-i42STu5JfIeXrKAM}igA92Z#8o@sOm8+z`x$}<-_+d>!H$HsG(v{ z4frEJC^vG10~*Sp@IIkXfwLQ2O@qem@WptnD(a1c7&F7Ruc-@3ppb;}Z2 zZa4Uc5%|*1c;+Fxx$Je5sESAAk{8>Nv4c#JqV+rRdNfCwY-?3yufo++$N zt!5SWf^NPvkY1>HuuBtOyYe<%L%@>Xs)Mdr&~3v@OgVeuPhYa3GQC@FThg`zPL%gO zDUk7v2q5VF-KSfypQ0bAs%o(0@-4&hTpydYsg@Ho)oa2*y!^#7YO(Z-#qfVz7RO$J zN^dH)yM(|(eOl)Rk7ylqhMMK(RuRc;KMC7OcWUpdwW}UD?mvtS`!@uszXA6Dmj$W& zqtz{`Ja-xoRU|&}B!W1LX174jA=_G=H60tN; ztH4vktkyLjx>g$cwLDC% zVph^-#@P)3K2!=}n(*r=Mx?biqAh&@HmUs)Hq8pLM2x;E61tqn;`8+{zz$E3us|9m=4wHkI0Tw_ zR;ga5%4ble`6=3}_1Gzp!W_x}s&sAzE-L91lH0=TmWw{XK|BoIYZH7*53sLOc-(d@eqf*O1h(ls+fY%!KQt!$g4)tV{m|uY;lxY5?%M6oz^t!Vh)D_t>W} zb6N0VVG}Q8|JEw~BY!S2U(RT$Y@JTw3rkYqzUfM~;%zp=P4}I4cSVP5l=sTG1pymf;)6<4AOIwrz$y~;BwnVIFq!M?lImdk;GD~bzJr0^rhF)I2E_H7MqI4D+zEuO zG@Tf?{naw@HgX}i-@Y3+$GwtF9kh2x<+~cB(B2QcsAekMH=Io1-cP^N_s{V6zdQa< z;r2(Q{(=P+576Klz9`=FDs;9sm8(WTo`Fp71@U7NlOEK*v%MJ)9M`YDw5Y8sKKJ3T zl7xzQ4fLk#B0S5*VrE<{hO6R&pB2B~{?B1CfY$O)#>kPVrbw|*o5?P$of`vI-CEZ! zQ!z3}_!`I-3PCb={sW!C2cnS{7HOtYgC!RF)Zy3RHa5wUXoyheq>KJtwpF`5t(wbpqI}9jg?_T)_;qfqqlXGNd136_>^G`}BFV;mwnK#$MXwSH!6ru;6MU{Uv!l=xgV$nDVKOS0;8M`;yFi=j!r^4XY(Kyz3AFTW1!D-;it8@wc ziezdm?AaK0AZ;)3;+_ju42>vvd`j|})8@lIYqG8uqPzRoswy1HlM+RDH-$a3aJ8Q( zbcNd6wPF`5dadoE+UpbtQWZ=t56V3Y&z@`zU6RTGFc_($Zh`L|(~&L|W(DSTzg<@@ zH?kPx>)mcp%@R2_n6p<^#n18DRms)S^{>A%uKk2k#bg5CaxO|DyFl?~3pNvU&g3BN z#`4~*v#b{DC(w-iAewbJYH)P#EG&s}t|mks znxCG=WVM=-X`8YGl2VNvSgJq}`%I#28LqRB(4hk%ocmdtvkRd7#OqdI=m#DEEe9yJ zYws~nUnh@d(mkp}lPvlCSvfW&zAM$(wjYmlk#Lis4UD0lk(Rb{5RbecVAk2=y@04f zOMxX97h0>fnB}tC|ow(m^V@Mb5OHx=L8wLveyxJ~Q}f0aG=0g`?B{o4lKSvd zs*PZDExPpv;AG0%%P)^osI474)aR@mnPlh4R_d%{=+HcMe((J2rPq;!`r9ZQfaPEa zW%1twa|BKLW2U*!A-d@mE8EKM;~v7)_VyX}+X2J)kgcCl8x$4V#+q?z=DP?QE}thq z4tEwi8QMHZRtTHg^a1r@r`HbMJKpPG+9_35WcKuY^w*OMy`N;iN)J4}X3J1VHAx)m z&)9r2F3f_iQJ#PCS?4zAdG(oX{H-S+W(%clBg7V8q7f+7Q+{vtFL!K?OSMn@?5k6% z6(n_a%lGh2=MwR8rU&N-3Lx5KfI=!sy7W?>8-!TGrP7);i)}@!`!49_&n7On(h~lN$$Xr4 z@C<8v7AbPQJJ@Ywwd>Gn3%b_^p|gk2vxDyAshNr+F0+`Y90W!B#&>yk^+7+z?we$A zSV1hIE_+2S-6~1bh4?AksWM+m7jPbPDPdh z3z&a|?;dqnooe+BU*P9mzkSGZYa_JNAc<#k(zSDrkgX%g@}}aZfR%8Hz&~-jur2U? zh_Q^RzDLz4gVE5B0e$jxKgdBu-AMynM-Ud2hIH^$)v{@q17B1fUTu6* z8>Z8!vIST=KzB87mj#K7I+e-eRr|q%z<@;K2x4Pfl*?p_TMK-wLwh|m94kJ*!>0ty zP)JEM=<1slhTXXmZ3wy*g(vs84wv_Kw5s96pie!*&^KFjKsyIvN;L%rpC6iy=p+}i z2mzO3V54O?m)}JBOPjnS0e+(ydSxc>+m^XOX@^C75`_FhezLLQ3HFNeM*Db$wf|ZE<+d-PB&^v49;h>8EV_IS(W8Wt@5ZqvbdV)y(gE{-Y&Cdf!p7A-`qa3{#eMxjF%`@!9~u5pw_D)vinz{^f_mE>C$%Fvh&0yu zXik>t_FSTxNH%rHISx zE`&~#Za&Ud=?s7|gY_!qc_^x%r)fjAe)E(Rd*7aTv&+C;^jrY(u|Gd`)1=!3Sy~HV z6d|20U#)*CRoS_{yECq#4~{>k(TaWye+D{bNA=fT;TKv(8(MOz)|xCyh|2t=^U7VP zc>TkU5$x8>zXpLKQ8^-5&EE|J~f^-yR*CmRO0Nur6R)h8&98ADZCBco5fY4=sPf_E|2mw)(QDz%A>Lr#S5F2lD`xsVGPE8T6^d-dkoeKY0NPHiUezGX4=D=j z56#Q!f@>G`4%|Er=wXMvL#i=o3SVRd5^cb`F*v%F9hDJbbp_<3sYZnjLfq#S-UwxM zv_wRSX@2VrV1K*iiA^tmuEs%}{b9rVi$Q^VukbzXYVN(l8iG5Xa_<#3Ew?^OC=H&R8D`dwEtO})@E%03y|8KR}ki+ z3X4S17X!a+fygJ)lsE`G z{9~CNPv0GGn+rJD<6yTrluQ>@D>tri%+)l0IK%=xZwR+DKSWZ*C&#WWW+oUi$53^? z5~>J-P_2m)82Lwx6$XKN37Eq!cN=$3Z?&{!4}&2N8KV{o(t; z@$t=IXW#Z0xD~bqJKN4^B^6b=sbFqT`81<0meNd39;5xP;O)E#wEO|L(Q(BWR1NM! z#Lk{@S?`%r-u-s)WZuKcvs^WR^d5_ zBN;wddUu_5?c2#g@V0&$JxaV9ka*sDf2^qWSv}Q$T&GR{I{ef=TKj;H-hrr#&M~~> z9-pr6)L-1cYxU>#{gThK_YU3FT{(n}9*vg9`{%^?q6~BMGc$9JY*DA4lnvP-z2Z&3 zP_hr`Tdf4@bXYkB$K(}a%S0@)eMb1dq-+t&)&Cmq;d{$=Jnrx{v*_5PRO6V13xhId zb7-`4j}_T>>MGY^Nqon$`^f`M$$L;=l%e7wYy@)+iUGVsw>kzPmdFFxu;(KO@qHZ0aQQ$;u0i$f z!wj(Hur&kkj6b>MgPcfOs7;xS_~A}e|KW6*QDJSA@l=BO>6bFLnMW~iAvWzRWonW7 zuEOr~ZOb^Q!ylT=1`0L;w~uFp;*Ba0lkUJSJ%;KJ%RYvh%)j~NWTq~=$Zh7$R@=IO zw&!r}-2C#|u4m$z9;6w2 z=Lu26#YbiYZHE;;(z;1LigRZ{vAOljosj7-PP{Q9x%_xkj;7WRF2Us!VB?(yOu$;Y z7`M=nTW~!J$hi;G@gC1hbeg?w)fhaOI2|Bchj#ON#iy9W=Je zbdCBxCd6U|;RYnNM7FS?C0Av#M_bZj zNi8^76mTokB-p-{zzn~c)p)qHx!P4}kIW9YV_^$Ln9mF^QPbjTjQX@B z2SF5f=-fp}ODwx{0u>;Hj3d2l{6dAdP}|mRd+=cXEQVoh8`}xj;Dz2HdIm;^ocCWX zj5{;fNkl1hX42R6rys;lmvu`)9Tvxd>UDHg;ke?Ll<@xDEU~R6vd9_jXf4(7CU~RB zGvD2nSbu|ndk3`lJa9-DQ>Tv&Up)DoTn-R``?aY1{YtvuoN<-D$0rfyu*(A`sl&dlh!H?q$}46Z&D~#mk!R@yfJ=T z++sNEK-Jn!T_vItBWQYy9F7^nQ?Mvc7g*o}ZE#>}q-%cNZSn;NH~;*$oae`cuIq{Ed z$T_ZZExDPs^U$Y;{R&$0<#+0aK4qR2_d1$9KXGLWvN+@=U=F)QW;nLrkI=~qFto;d zJ!bAcaR>OWGijC3_369TQZ!swd&8h<9?Cxd%+!5~`t@OxMoo`I8?FA3+)?o*YsGcO zLKi)~YMX=XGU_!|r+1n9*}JA0eBG}{(BG(kmVv*wxXtW4B6R)XM@4xlBOpf zSLux>wE7II+(rd4GrTP|&))nzdf2<_G=?rn8vP+%G|)@z`h~jXy2cj`){!3Xu{i6m z_y4u`UQtap(6%W4pr9ZKihz`;Gz9_aornk+5K!q|q;~}AAyE;KE?v5S)Bus*2^|3e zsgck_lM+ZMAwbA~KleFj-+jm4PxtMPaUb%MjI^)Jwbop7&1Jr({oxPcgPzW;spi?U zx>FtNG&mdBj_H~c>dIGAY*8mMmS>R#BzMGyOHzDJo9$AN6#VjA zR(qi#mkTuB^3o(EJ%EbHlgx(S)@Lz&;2uXqpiPL===?9*Flu{_$o7arm?m)JiYZCE z7gOe7^cjlQ*E9wjNUoWxTxv3G)JeJfu18()BPPlw5|Ega_-VqEX)XVNul(vkjWO{s~bHPWrCw1D@P(Vm~tcv`$3_9U@{&#GI!Ve#ijQQVV zBPbxBNs7F4o?4kIjX}*eC(2A3;1C{rPU?+(PB+ zt<$LgSwU+Y2SdXf!0!NkCx}t)4K{PeL)vxK@%z|LG9)lCPWIJj79~R453Xyn%u)Lf zf4ekBMa9xJL3R>|BsXabb#;x87T<_Zi3%rz#0>yNssaRwPQQG)*}9IWVGjr^yxmvZ z3L-0{2Hw0oW}$8n3fxal<$JY5>kH*P`+MZIVGjW@051@2&AVkz>?qp$CZg0ss#k!So3G@PqOJlH>kYi`q@!2s|?OPk&G$vnt_&@kM~rAY+E!T;iX4bi>@ru?7BsVd!#vk4~evdJ9r) zzn%E|Ty)$w*fLn>1F>&wVSi+k=JP1cho@`$V<~C3L$`!_;VSLSq?R*Pc&7*qC@AdH zl~k8DL(}=jj&2+rRzOs{CGrIB-#9$DE6=gqiJW3030jj`5nb^5@!sWmGdk#f0*hR9 zea5&){bW~64W?=J^QD#R&@Bm7uk!BogUYMDuS!E)KBkzNA86+9PB#Y@p@VsJdBw7& zN7;sX{+w?a;3QvJEk;n24n&CVylT$S5xy{(}Pdijjt# z!KZ$JBNZsdb_HNmco~4HvLSLA=+WP@`@)&r|3d&_prnVb5bIQ6?JKQtF}kIZ?$lD; z($=UQaEGJMbS~^gBCTLsU=n2!Ota#rPtfmZ(vOo4cuGDtR_784Dm(nT_9v4Z7bRzQ zWVoq1G$wn()1)3ynFoLdJBhRC8E+Cc;^R!Zzk@JJ{>{-NjeyN*;I)Y4zX3l#dpY;) z^j|8n&Re*>t<|I>uw((XuK=#DLb^!)OVwe0!n3R%04FOIEa{!!*aQB>A{t;`oc{a! zK{IlDCkJ5i#ebW4gwzcWpMLqJaIo)MHYaU z*FgWk{}cx}QvPnyxNgk`?*y_fm-vXqT9xdjU_BaAPJfTS)4_uB#>~sd-!I?1n*KUZ z*H89wkTE78IPG;Q;S!IpvzEB7vAb0JWf9!miHGzcp=v;Q(7@g<3AR1vqxs_$SjX|; z$Kv(+M;7_3d<;8U?_zk=Cn1dLD<%mq(Zx|OA=VC#J z?7F6bg!M0SYm>Y}RXUIFSK1d;A1J3r5s;(+<4)_-dkftEQlS9StY-`$9gw-hf|-1gLaynyW4Ss3hFifCa8<&FnmlNyBLqcG8u8{7Y3Q zsxd?XyKx{gD(B4ra?*v| zL;^C<`*)3(e=U2K_6qGINC!=Pa;q``IU6K31gT6> zxQ(q3qnrI86I|<96aEwnT6i006oT3fSDC^Bz~JT4f&hWY3KQIgmY3h2Axe_P_t%;v zgqnEsggz+oe0>^Zw{cL3db@;Tl$e7VG61*r%hF)e8Fc~l@TPx=g1HVf%Sgeibciux zZ@S?OM!t?e|LD&Kx}kJ)Z1~n7;!-hpPo{~TJ@12#rNi5|4uB!nPJ0!q09WsB>=5p? z`c|rf@)$Yei8}awFU*J1vxwJ5vcWJ5G;IW#%u1(r(3soatR7QPV(Y|@lDJ-0W9Jub z8ved>iarH|0wNV2y>qnkK7V+{xz(oZ_jlP}=9?czre~T@9MptsV<&D4;a2T(vRE6z zAMw6x;XT+g-EaOe#!HxJ?G3&FC7nJKw`j4zxYv_+s<&28HH1zZJk?vA1x9P60pGLZ zkF8Geb{ts6*Fsuu_S84nz=!mVq8_}mBJ6hokOi>re1%Y6KKnK*4pfy8PJuS_x7Hh z_x5j~Ult>Ypt^?b4SjV$eYd1gJv!yG*WwHKGULw)R&?DpBV9+|T z`*rrnA>NUqY-NK*lI|RL>%73|2=-V#95;>gQ~G7m)22Xus{v`GtXZt$i`66DKA#M9 z2Vr$u7ZMhn`jp;Mq|<8_Ng8t7)2({8iIW)b_@h67Z2wgI4BVY%RMlgcen!V-@R>LcZeTcz+6DGOU_oT&0&M^L!=dPHbJUgX z)cUG)3$sNf@30rCiuSQ=F+4Fomi}bs17a-U0i5R!o(n@nlm&Rc_}-YPC_I{>c%RpD z8O#6WtK2I?uVO#F+eQH~snG>OB(v5*g*u>rI+PLMlcp_Nk!}~TW+s)gcC$`9WO`&^ zMh-FSbGY?C$<}~Yjj33)6=#|{9{GM&--y75nKe!vzs47E+XVA)L_%g)Y(I2>uD{N` zGkHU4J^rr8aDzvrU?~}mHLz%O{Cj@jD;W~E~ivv zvnGvsn2(9;(bMRpCbj#t+>DYjG3W112=?-tvdEtmfwKF-5@ZF$W&8qDA_Q|;QEF#8 z)_IDfU7Vnfd{5>rb2Xj~%K`dwxXu@;``E|0_uFC8B-{=U$t>;A#fQ%R(ddzb>W8Sll zK2kj=(`mTYLboHKrM=hi!SBO9)w@*+5?3If2s|RZ*vc(`z&nB`Rjc3O%BIXo8M7nMWB*NhV`>q<8_%Z@sLJ* zcxegX7G*L`mJMu;&Q^F@c#^kB*1PU@rv*{u?PIOx0>ySJ=ihU4x_}g+_P{aYuP&i`5MXoOsqv zCj0vt8&AzvosONclHX<$Q_oYB=vSf(BR%VIB0PsrWcrE80{4k=L+b@ge(bDUtbgVB z##nUt5ip}?+^NDA+LIx@5hZ1aqWqd*Ih7Z454E0qT22U`uPw;C8sme$9d&xz?kL|? zuA)%Kj<`1n39_7Bvn9+ukrx^iZUIP@)`@HRQEn6bwIX~mRsHM_e)eDa>dW_QKIJzk z2S)qf$XP`t4!9>RF47gw-`ncv*sEbJU-&#vXP{FFFOM8kAV+sW1l2fzgjvj-%!F<= z&vG=rcux^&S7((6)b88Gt9Sl}&t%FB3{JjJpIdX%?vGjOPs?5m#x&*rmc&`(V@RPm zYo~c)N&QLFhzw79WfE~Bxf?IKndSjQ(=I&k-V3_5hI(}$1E(i_`mRbzVVi%1>Ik_A zy(FN0?)I&Y!g+|%Trt@cBYh$TY?IkG>(u_-0@@Aa^W^_U__qUD>W38Ae9&H}viD*K zh3T{NXcs z01gNC=@Y|5ZKK&4G1>L;`r@e^1yc6%V)!l3Sta$#O$F{2N7qG5KF-nn-P=_}4(S6R zwcR5Lvvn;}N8TOhn`$+F+eBq*&i-n&H4(QmZ-`idhr_>*_Ay~TY$*p}N47ZKwOP2W zd)S_Zdj&F5d!%=Agi| zsiYS&rpHu*+}-myw=SOxA7?J1cj}fv@9wvBEpS#%?A9l{_FoFFr!6_KNTWLahqlgt zqATrTtM^?Xn>I`dH+;YJL0Q;@u+DaAilODIi*`#5EChaY7q+$x^X=gRhh{VEm%oun zZc0fLjy={gGB&dmRd)<_I;6O`s&x}HEawL+i$j8KIb~#LXDa%}wp0_q&(M1tJz_J| z%VIrG9nyM0Oi;GB!v_%WQw#BD;@d(cUf?CeeQR7Nfapu-nJ`wU=(O~=4C{;A3BUDx z3o+(f`&!L0TQOtBNrD;cGF~^n5SMuJ+seg0nFtN*BQC49iI$^}_Q9TmBy5~Qxfi}b zCD5tqW!f5Y2|9BIz)zW9>Kkakh5f0HRN}=EMaG6kl&{x~HyK@noC-uO|mcrS9b&1&Z{kvwDEn z%G?&q%P@ls$`0HB>gV3`WoPuV5~GZk!Fu^rVtd29X~j!_-Hr8;0^m3b60Vt0h6(iQ znH)6QMUb0gxCpo7!!i^en|l-f>v(yQOr3#xcCV5|%Ikrc&x(=%0k6UwMQI0SQ8jSV z4b)F^HVFrO4kDW9h-X+3AoTa<(vjdAkv+mv)BX$-KU8hFoW8ckJ+8X)HS50e1!;m_ zOuG=t5z?9}!m@2ReN*D`uyhngQ>^iPrJku7fRFq|yjOVbX$Yz-z`T2ZdwO4{f|u&D zi7Bk-0+`p^pX=?OA$%zt$haYTp{QCg;KYLZv>@@z_oU8~S$b%+P$r*PpPJ8E`pVES z%=YsolTa3uM3aQ~F(DN5{(xo<3&{r~h%`m#dwtxT=B6sK^DR6@pl%8%jMc17U~eMB zx<+w-fcE;9~ zdwFL^vK=Zygp0YU{AZ5D z2Q}vX-&qVzD(8E+a8~BrOst1&T}aaX_&)GV-yn#w90SF`;t-xUlMtI<&Tf^k>m`5t z8hmr5{vxc`7`y`iNMR$T)5Z6|IDh%BzNo$WxJx*@U^XZV#tJ}6k4`r>t!mio1wyZ= z!FANofs7Vb@sV3jH|kY#Fg5-S`Ihy%ZJxE+Y)Gfh_z#qJ37C^#FT89(VCo*?{H!-D znq6AUsagFrKKE?LxI93ZLT`&lSUasu)sEhDk`TX;qy2REj&+|r;A+!k6}uuv;s>tl zf2nSz1}ZVR7yq2OtD~?RY}s`9#49(0V5PkhPr8Hdp0~8DWx5f7c#>Wd*0}F!qxVd7 z(sOuN4=u;UK^QAlJvMg51Kt;hNk30ftjm;JpUYZt@Ii3;VR7duW^@_VzivVn#GZqU znr#|QPr~V2FC;=E{~36{-N5=Mg;acIO&Q2Y+mR%wK_+H<7BRAHUT~-1izXe@)m=9q zm+6gY$qDHV0?K>qirnhlIA5knc#ZXYU))REH>EBaBDKf*tXCY9`()**-zxz)IP`tehpWD(^fAKO(iGWg?Ko!EU)oJp{nTe%8rrA-9HD3ISiJ4omh&D6t(_o~ z|7bL)ue^A>aCIsy4&d}N?}xRIwynFlHy)1&>qd>#ft_^?_FRi98;pfm))Lcf51z%` z+5tNrHG9Uk150MpH{i~X%^j`9ybi!uGiz`er~26V9lfulGpo#(6ML0XiqXXqx(Pi3 zVZZlH?%ysItYlOUdkdoZm&!qeeyMKAs+$j!T5&h|%wkC_wYWr`OEfqUa@^Sq7g$}O zcRZ9V^Jow%&~>pIgSg~RjDuM`=3hdNz`DHzzbgR{Z_5!#rMa&w0@DY=HJm+zoJo=e z%yBAmMQGo^_Wt7Xg8SFqAB=zBy|4d6v8OOPb#Ag9sv$;2XL6=Chn!gTDzSUc^ zKx8q6vGp}-*Piv~YDmPKhV?&IC3%`n<^QUUM$FW#ne~jC43l6tUk{HFMlOd zv$lP!GT%0{2oL7q{}EeF74VzLK()ce%3Wj4LaHHxNGaH0;q!}7u@LUwNgbA-qwMcw zZPz_!V&bh*B)f&u!=yi#yT_z3v$%lN*KlqFRCaMzLwY?7Qei#q2(MLt1Fy7|1AfZZmC!Vi|uCV zTNY3L{zcT@(ZkZ+qd{+d{&c(PR2e}**Y7Q&puN>^-WyqBhf8`?(9H&7`tJ0k- z9ZHNM#N0~5pz7@sYLYmggiGQY*vVA@bl-$Kn5wV^cq?o5E!WYp*3Y{)FrV<&;Pr-b zl&gh*BFJA?JOr>iGAeQwBek0&S%ys@p|s=keuvrZ30IL9XNQI0+K^DZ57rKTgUrnh zD4V{|KVIkjl1wgJqE6URr3rew!8(ObqYPSIZNc}yb8K#nT@HB(SCIQ{^U>xJ1FSW- zh$-mk3Z-~y&Ow$f(WXlNL!GI*yrpUTaAhn)cFR}2fwN`+?xy#9r3+P`*3F7Pj#L?Q ze&cwjal%*FEu=v2OAL!-H!s5_wQeeT2G)q~cHmcpLZv-PS}T_3SdHBC@M;Im+6fTO z`>XOlH9H!-?Ixl@G7sT;_mC6SFp1&)L8hyrh#}gsZ##>w#hyc@vCl*l;xn}MQ%Hh% z>uz9s&tf;XV3!J8%^72CLGM~mSObKY#dOt=BIv*$d89=3kajJ%pIZo6?Lr#HBHUl_ z={#08TOC~wS+^CI**U(N6*_k<7`3XjSZcqie3g;g(pcp;Iz21A*{O zol4ugZnl?@JI8C!V$BWe>uTa4mAi!|Ut?7cTCUw-@_x#C#$VJgrQq8<_b_l;n&lxy zpksi%-AAFObhguxu44J7-8J&cUGN(}8Yj8g%{F54g-Wi*W950Xn60MtGaat=3<~88 zo}OmGt^~NpFT2Uyt#sta3Co>T`M-F+UbisZAXqmJaYa-CQ6Ub7g(3kAlsIp_PBg(6 zqQc(>D~71`!tT{3BXH{cT? zwu7voEP`qc4>QuDFcW8rw<_yG-iYS{#AHat+NF_=*It$*Y+ih_S70Fo?(zApaS7;P zqs1wfZ@xCf9Id_3Pv~d1CmCj9y-)Qp&to=NL-b=Yhb|Z(9nV7I^zcm2 z&!b=p=D(d`e6rUcxRyFM_>KHpFzYi-f&TPDrr4y&-FBpws~lY}CbK$X8$L>J2i6Tg z26j}se7|lsH`DF0o6R_LSN%@gZ&_v4ibawzx|`cr_57;{^aYR7k8wnn-N^(lMP!!FrpCY1Z5RgDzR(JDEM zBA@Oq$#Egw;gHmcaY%*XUV#cg^?xV<5K?ci)iZz7>M|*?#KO6mr=_59z3FYPNDtPl z1909mG`{-`^re1oiF@%Hl##TDMb7kNS&>mnAcW30m+3)U(RWfleNRPhe1aKkU?jfz zQsE!*{sGMbzT-11$Z#+%`3~V9Wuep4ku#lY*XGw)m9-zR#CjxpL`KUv>27R*IlWcu>%x~=_J%4+Z**NCI7eT{>Z&u`nIJSMf|z}t z4HaG~ai{cQj`9MRIA$3LEou^_N+~RTOVxfyRcH5@ zC0Q;D+&QcERzxC8ky^ENQC-t=x8vk&!f4*~-wHFCWT2v2qLS;Vcvx4qyw%sn;XNq2 zS#ZpwLcrwsBo93px~G*{>JbR(oe}iQPucTp@T=bR_a$!tDu|l!!ZUiL36*ug)H!TV_XpOf7MT2Rj&qYW3*`f*5U7v9u z)ao-_1 z&z;H}HV)wij4_gBHiaoXVSOEQmh$L=%BoQ@FcX%EWP}<{-C8yu zLM6{XBAwV7ZN%sOAPdJ<*JQqEiCS2Y7szqE%;h92S+zu^tOLLOCXIQ6y?lr{4Ea(^ zNLMJsU1MNI)UcpEZufYOEDRp5I;u)>GR#VBu_&!A&&d!u4@!hOpGWytfI6xJ1_uxH znqwY$in+fap1g3sy3U(LyTXU0o$&LLv!;Wg7nzlqzN!^DQ~1)|MMigfhy)7>v17HT z<+C9*{cgsyU>4Xdms=Y<{qW`B*LIVCSF+9DkUbr+Rad+KtP`jlJ3@}oBTOGu+J!r< zhC7*jOK489d*!7{`&kudmCIpoDCgbIQ)IODf|!h!eCfJijzFjkBW5jGz`wwBh>78S zy0w#XTjMQqRaC}H7o{?E+n)PNzqSP8#?JdQ`+2C{bY?e>GcgNVG(Hya+Iq;Upsaq9K;j`?WkxR^N6_XRP_|##DN9&?RNW-qv|i zx6%stmsQFv&s>%r_SOn8w@bw03|PsR12&Eyt*A;Fy5^MO13&2h%PD2x9A-90R$c>{=27>})9Qg0Bac zj(;efUek2hXjNQ38)e;2ZFc`C@+L6wcGNvIDUuRes{9VQ0rl|zQof9>M{vj$x~E{) z8kXl5o5*?@1f#c&Ii|6gp2r^IvGtJJJde_1kKN<8Bd{iG14EqZD)T}VB7buOGFBm? z9T+}+<5Rr~af%vTXomdbR6jLyUZJbgD=)0lX)OuhpE}&L_dKpuv3N5>B)hV3MI=Zj z6{DDy8O(kIC;9a2hZ(oBlG`lhkQ1-PXU6M*sT#a=#M>JZtlVku*qk=#t-WF^;7)P4B8MV=Xo* z#=tJiW3s^26{Of(G@-lE4Wk0^?H$ydq_eb!-_6ECZchKC`+Da7%~;a(;>zpVDBZDN z!giumRE)w4U|S?f$njHM?xzgTaLV1bq5{YAXQ|&^s>~}|rzhmE;nKJH<4Q?v!TM!S{}Vu)s7@=`Y^UB`DDka`K8s(4~N z!}z@Qd>_Y(#d*%dj@F7lB~7nG+FTDAy6+B(o0v{z%klHAjU?*19$1D@LiF|>`LPuK z4hO04lZeUWJbos}`!YH8t8an=-F?UVaVhE{!91C^(mlh~oNt}EQO#fNa(@`qaSu0J znL`+&o8=7(kR`k{#s`t-1DuvVZZKKO1iX$d66_ogvf45$JR09r@!?i{c0kuq9Sy!m z$4I}znOmyzn>rlt@E#ORw*9uLKOYjut+mgo*(jb44NK@soBeF=;qy-8jaBa13s^5j z6!4ey3Gq0!$}0`z(e((d!qlZ`Oosmw>5bX&KFdkl%3VE9G??AND2xa}g1*OLD^;xy% zx_HeR$BVY@$&mG@gW%{P45FpTjyI7J{7iU%rY53Ehgv)&7|yLz3?qcw%#R~_7>2HBTntiFkqC}Ldp)r!Z}>f zY}Et8nZkGOoC&1RbA5UhpMURy2JC=2^+8X@DVRbxdgeSyJQmn$tf;IY}PVYYmncL@+`wen?mbbUol5P697cn-m(DPYUgBE*$>oBVn?A zGc}$+u8>C;4WYU%&Xp|aeaPDu0@TSg{=oV43Yh3$td)&`@se`YCZXV^MY_3IEsXge zvjv@(TPijt3Ez8Ji7hHJ_t#1l4S+iobcq9ZiKzaRL@W9M*TH&q<=!QP`q`A-IDR_A~XDTJY7KU zl6`-~gF|jcWp8fTA2m}t$h|9?3#~UfR{8L2u-6E&H^(Um46c6%xnbW`=6v zR#AV>k)I@Y*#;yPq$L@ogbYgy{Gz>L(QSahld)cRH1Fj7ir%#?5Q{Y3E?GS!5NWAV z$l|Wy(41h9wIua1%PxtOaTqI1xx!CSTY`6T!mpD2wl(7>p3SmW{3Ozg^u{RDIFEFF zUD+#O&S~u63B-Vh6Jd-&TI=-8bYC^){${%Jong{-S*E?xe`w#t%<2IDSF6KKTomasc|cIMMibuQ~o;V^UgK*SDd*AKj#Fx)0QK`J*3CVAj|VtkEG!bE$cpNcrCOLcSotSh!ulE z_H;v7W9dSx3gKq&H|=r5h)O`(Wyk^KV~^NjVkBFjCnQGiy1?`6sILK7`sPbdSNROO zv9?gmbd|sHoUZ3hUwc%+JLNEw{Mr=f#uAyGdgC!@qye_@ zXDYHJE?-@!L*jcUjc++UJk07=-6Ran6I#gMp%_YUf1+2y-l2kRz9JmK{JtB@Wf}A) zDXwf&5iE?`|GUU~>+dMle|=Dk^}#NWQSOpFwl&eUL)^C7t(Hk<^Ig@ww{f3? z+T5~>KlalfuOQ~%ahfg%dl3NlbKI31M&XY)8G~{Zn{PcISnrh@ANE~EIj9PMf2_z# z&5f8UDJh8S886y=S$eN`H^~`nke%KgIp`%9HP-X`UYAeYc(T6hSe@_wl?t1JnN6KL zb#?Xi5=%`{w=)S@j?_8D2M8%+k%j&|e_(^ne{Q0_Fi5r`aW6ArXuCwdk|w&Fts|vU z;o`5_K7y0aWeY<7EYidds&?`!Wh}vH;GIgq7}~H3KLvxge)l$8%*5ivzeZd7sJC5% zDfO6%S2H1DpShDaPa1c_*igw&;6^r`L1O5a!Z! zm(9Hfg={a}1#hgjaaXn<+Je@SR=cm)*dX zK#>Lgt#uj8Mf?M_zq)gD$8yzkqDk4CtYFA}v8JLR6D2>v%V5{AQXy{)!9#3MM^dme z=i(TJ#|csF6y#o+?(nT4&PEE83^7J<6nW@Z(T1%y6*bcFohzB2-TJOyrtR*kmN16=02rX-06j}$G zgcb0=28vtCROO2|Norbzy$FxmSWlhmsoIvc8Rfz`VJV52ReO_bUXOTxy>r!ya<1Kt z`nY!ae&E{QM6^LgtFN;<7XW3T6fcbS-(XVNlEEA#NL7 za=E_BpW;|OLzX_nj=h)_slAWjn&J;C|I7}9K0@V-|KPk@?9-_sZ-kC8<4umj30XJ$ z0xPGZ(A&RrZI9s2qIzpB4fDY~Y(!n!ZLlTrArUn?#N$c6f+jzXx>u?H>n|`ekJ)P& zJs<3*Vg9Thpb2=(0s5{BWPLz;iW?dYKNXwBs0q{Y=Pb;8+4rIGejxZqpLOqsu?C34 znsF9zHQRHTqO24!#q`+Bz7<#r*}U>8 zW57=>G3p+K-%e)M-vJ!i4sueFN|l|KQU)0XXz;qu%5B_}%%P`_3&d8b+@p*DGqq#O zneL!o9=35`cZDH}^6NzIa5Q?*u3IyU0mmy>ITF>X4Ecq?mB?~bA~cUHG_7>PZa zUlilAvz&-@^3C(Ob`Hv@LXvd=xJ$t!2{x#YbKAGHD9b6U{yDP6<6U|M&ghX#4+_V{zf% Gng0v_2IZ0f literal 0 HcmV?d00001 diff --git a/doc/library/index.md b/doc/library/index.md index e072b1036f..642bfc67e9 100644 --- a/doc/library/index.md +++ b/doc/library/index.md @@ -11,6 +11,7 @@ compiler/compiler data/data datastructs/datastructs debug/debug +Evolve/evolve functional/functional io/io math/math diff --git a/doc/requirements.in b/doc/requirements.in index af341d1323..b828b68d43 100644 --- a/doc/requirements.in +++ b/doc/requirements.in @@ -1,10 +1,6 @@ -sphinx==3.2.1 -exhale==0.2.3 -sphinx-rtd-theme==0.5.0 -coverxygen==1.5.0 -breathe==4.22.1 -myst-parser==0.12.9 -# @mmore500 2021-10 -# docutils 0.18.0 crashes docs build due to exception -# AttributeError: 'Values' object has no attribute 'section_self_link' -docutils==0.17.1 +sphinx +exhale +sphinx-rtd-theme +coverxygen +breathe +myst-parser diff --git a/doc/requirements.txt b/doc/requirements.txt index ba5ca8f558..688edaba1f 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,85 +1,84 @@ # -# This file is autogenerated by pip-compile -# To update, run: +# This file is autogenerated by pip-compile with Python 3.9 +# by the following command: # -# pip-compile requirements.in +# pip-compile --resolver=backtracking # -alabaster==0.7.12 +alabaster==0.7.13 # via sphinx -attrs==20.3.0 - # via markdown-it-py -babel==2.9.1 +babel==2.12.1 # via sphinx -beautifulsoup4==4.10.0 - # via bs4 -breathe==4.22.1 +beautifulsoup4==4.12.2 + # via exhale +breathe==4.35.0 # via # -r requirements.in # exhale -bs4==0.0.1 - # via exhale -certifi==2021.10.8 +certifi==2023.5.7 # via requests -charset-normalizer==2.0.7 +charset-normalizer==3.1.0 # via requests -coverxygen==1.5.0 +coverxygen==1.7.0 # via -r requirements.in -docutils==0.17.1 +docutils==0.19 # via - # -r requirements.in # breathe # myst-parser # sphinx -exhale==0.2.3 +exhale==0.2.4 # via -r requirements.in -idna==3.3 +idna==3.4 # via requests -imagesize==1.2.0 +imagesize==1.4.1 # via sphinx -jinja2==3.0.2 +importlib-metadata==6.6.0 # via sphinx -lxml==4.6.3 +jinja2==3.1.2 + # via + # myst-parser + # sphinx +lxml==4.9.2 # via exhale -markdown-it-py==0.5.8 - # via myst-parser -markupsafe==2.0.1 +markdown-it-py==2.2.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.3 # via jinja2 -myst-parser==0.12.9 +mdit-py-plugins==0.3.5 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==1.0.0 # via -r requirements.in -packaging==21.0 +packaging==23.1 # via sphinx -pygments==2.10.0 +pygments==2.15.1 # via sphinx -pyparsing==3.0.2 - # via packaging -pytz==2021.3 - # via babel pyyaml==6.0 # via myst-parser -requests==2.26.0 +requests==2.31.0 # via sphinx six==1.16.0 - # via - # breathe - # exhale -snowballstemmer==2.1.0 + # via exhale +snowballstemmer==2.2.0 # via sphinx -soupsieve==2.2.1 +soupsieve==2.4.1 # via beautifulsoup4 -sphinx-rtd-theme==0.5.0 - # via -r requirements.in -sphinx==3.2.1 +sphinx==6.2.1 # via # -r requirements.in # breathe # exhale # myst-parser # sphinx-rtd-theme -sphinxcontrib-applehelp==1.0.2 +sphinx-rtd-theme==0.5.1 + # via -r requirements.in +sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-devhelp==1.0.2 # via sphinx -sphinxcontrib-htmlhelp==2.0.0 +sphinxcontrib-htmlhelp==2.0.1 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx @@ -87,8 +86,7 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx -urllib3==1.26.7 +urllib3==2.0.3 # via requests - -# The following packages are considered to be unsafe in a requirements file: -# setuptools +zipp==3.15.0 + # via importlib-metadata diff --git a/include/emp/config/config.hpp b/include/emp/config/config.hpp index 4f0fe3c93d..dccfcfefbd 100644 --- a/include/emp/config/config.hpp +++ b/include/emp/config/config.hpp @@ -402,7 +402,9 @@ namespace emp { for (auto & x : type_manager_map) delete x.second; } + #ifndef DOXYGEN_SHOULD_SKIP_THIS friend class ConfigWebUI; + #endif /*DOXYGEN_SHOULD_SKIP_THIS*/ ConfigEntry * operator[](const std::string & name) { return var_map[name]; } auto begin() -> decltype(var_map.begin()) { return var_map.begin(); } diff --git a/include/emp/matching/MatchBin.hpp b/include/emp/matching/MatchBin.hpp index 22cb215fce..c9199e9e85 100644 --- a/include/emp/matching/MatchBin.hpp +++ b/include/emp/matching/MatchBin.hpp @@ -61,6 +61,7 @@ namespace emp::internal { using query_t = Query; using tag_t = Tag; + #ifndef DOXYGEN_SHOULD_SKIP_THIS template < typename Val, typename Metric, @@ -68,7 +69,7 @@ namespace emp::internal { typename Regulator > friend class emp::MatchBin; - + #endif /*DOXYGEN_SHOULD_SKIP_THIS*/ struct LogEntry { query_t query;