Changes between Initial Version and Version 1 of DescriptorHowto


Ignore:
Timestamp:
Mar 11, 2010, 5:27:44 PM (15 years ago)
Author:
Till Crueger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DescriptorHowto

    v1 v1  
     1= Descriptor Howto =
     2
     3== Introduction ==
     4
     5As the name suggests descriptors describe certain elements within the world and can be used for retrieval. For the example we will use !AtomDescriptors, but all the examples can also be used on any other kind of descriptor.
     6
     7=== Using Descriptors with the World ===
     8Descriptors can be passed around, stored and calculated. With a descriptor you can tell a function which atoms you mean, independently from the state of the world (e.g. you can say "All hydrogen atoms" instead of a specific data Structure carrying atoms). This means when you add a hydrogen atom to the world, the descriptor will automatically include this atom, even when it was created before this change. Descriptors can be used in several ways with the world:
     9 - Accessing all objects that meet a criteria as a vector:
     10     - This can be done using the {{{World::getAllAtoms(AtomDescriptor)}}} method.
     11 - Calculating some value on all objects that meet a criteria:
     12     - This can be done using the {{{World::calcOnAtoms(boost::function<T(atom*)>,std::string,AtomDescriptor)}}} method. This method takes a function that calculates some value from a single atom and a descriptor.
     13       It wraps this function inside a calculation object that performs the function of the single Atom on all Atoms that meet the criteria. This object is not executed at this time, but can also be stored
     14       and be passed around. Use the function operator on the object to do the calculation and retrieve the results in a vector.
     15 - Manipulating all the Objects that meet a criteria:
     16     - This can be done using the {{{manipulateAtoms(boost::function<void(atom*)>,std::string,AtomDescriptor)}}} method. Similar to the calculation method this method only creates a deferred calculation, but does not
     17       yet perform any manipulations. You can simply {{{call()}}} the resulting process when you want the actual changes to happen.
     18
     19Retrieving objects from the world usually takes O(N) where N is the number of this kind of objects in the world. In some cases it is possible to speed up retrieval and the speed is improved for single descriptors. The
     20{{{AtomById()}}} Descriptor for example will find the atom in O(log(N)) instead of O(N).
     21
     22=== Calculations with descriptors ===
     23Descriptors can be used in calculations. These calculations then correspond to simple set operations, i.e. set-intersection, union and inversion. To calculate a new descriptor from existing ones you can use the operators
     24 - {{{&&}}} for set intersection
     25 - {{{||}}} for set union
     26 - {{{!}}} for the inversion of a set
     27
     28The calculated descriptors still need O(N) to search the world. Descriptors that use speed up mechanism can be used in calculations, but the speed-up will be lost, i.e. the descriptor resulting from the calculation
     29{{{AtomById(1) || AtomById(2)}}} will take O(N) to find those two atoms.
     30
     31You can also assign a new descriptor to a previously used descriptor.
     32
     33=== Creating descriptors ===
     34
     35Unlike other C++ objects descriptors are created by simple functions instead of constructors. This has to do with some internal mechanism that have to be handled upon creation. If you are simply interested in using descriptors you can just think of these methods as constructors giving you a descriptor of the specified type (although you might note, that the return type is always the same).