Import('env')

# All .dox, .pdf and .pdb files are installed
env.IMPModuleDoc(env.IMPModuleGetDocs(),
                 authors=["Daniel Russel", "Keren Lasker"],
                 # Provide a brief description of what the module does
                 brief="MODULENAME provides a divide and conquer sampler. It provides a simpler interface and (hopefully) faster performance than the original IMP.domino module.",
                 # Provide a longer description of what the module does
                 # This description can have multiple paragraphs and all sorts of markup
                 overview="""This module provides a sampler which finds good solutions over a discrete sampling space. That is given
- a set of criteria for defining a good model (encoded via SubsetFilter objects)
- and a list of possible states for each particle of the model that is allowed to change (encoded via ParticleStates),
.
it finds all configurations of the model that can be expressed as a combination of the provided particle states and are accepted by the filters.

The criteria that can be filtered on can be any aspect that can be measured on a subset of the particles. Provided examples include
- accepting only models where a certain restraint has a score that is less than the threshold specified for it in the Model (RestraintScoreSubsetFilterTable)
- accepting only models where no two particles are in the same state (PermutationSubsetFilterTable)

The key idea underpinning all the sampling is that of dividing the set of all optimized particles into subsets (each represented using a Subset object). Good conformations for these subsets are found which are then combined together to produce the score for the whole model. A conformation is represented using a SubsetState object.

The idea of a Table is used in several places in the module. A Table, here, is an object which, for example, knows how to create a an object which can filter the subset states of a particular subset. That is, a SubsetFilterTable knows how to create a SubsetFilter (via the SubsetFilterTable::get_subset_filter() ) which can answer queries about whether a particular SubsetState is OK (via the SubsetFilter::get_is_ok() method). This makes it easy to perform preprocessing to make the SubsetFilter::get_is_ok() calls faster. The table idea is usedf with ParticleStatesTable, SubsetStatesTable and SubsetFilterTable.

Implementation todo list:
- replace Subset with something that uses a memory pool if allocation becomes an issue
- have a central table which lists dofs left for each particle, if any node can't find a state with the particle in a given state, it is removed from the list
- make things work with particles that are a function of multiple optimized particles (eg centroids). Lots of things will have to change.
- provide a means to filter a node based on already enumerated tables for adjacent nodes, this can probably be subsumed by the global allowed particle states table
""",
                 publications=env.StandardPublications(),
                 license="LGPL"
#env.StandardLicense()
)