ESPResSo
Extensible Simulation Package for Research on Soft Matter Systems
|
Most features of the System::System class follow a simplified version of the composite pattern which only uses leaves. A leaf contains a weak reference to the parent, so as to allow coupling between siblings. For example, a long-range solver leaf can access the box geometry leaf to determine the box length, or the cell structure leaf to verify the system is charge-neutral. While it is not mandatory for a feature class to derive from the System::Leaf class, doing so helps maintain a coherent interface between features.
A leaf can be grafted to a System::System instance (the "parent"), upon which an action is triggered, typically to initialize derived quantities in the leaf object using the properties of the parent. A leaf can later be detached from the parent, upon which a different action is triggered, usually to deallocate derived quantities. This is achieved at the script interface level by overriding methods ScriptInterface::System::Leaf::on_bind_system and ScriptInterface::System::Leaf::on_detach_system. These callbacks are defined at the script interface level, because side-effects are usually easier to implement there.
To maintain separation of concerns, System::System leaves are stored as opaque pointers. To access the functionality of a leaf member, it is mandatory to include the corresponding header file.
To add a new feature, the following steps are required:
src/core/feature
.ScriptInterface
class of the new feature, which serves as the connection between the C++ core instance and the Python instance.src/python/espressomd/feature.py
.System.__init__()
in src/python/espressomd.py
Please bear in mind that a stateful object cannot do a full initialization inside ScriptInterface::ObjectHandle::do_construct if the managed object constructor depends on properties of the system, since at this stage the leaf hasn't been attached to a system yet. Instead, it has to store a copy of the parameters in a std::unique_ptr
via ScriptInterface::ObjectHandle::do_construct and delegate the actual construction to ScriptInterface::System::Leaf::on_bind_system. One can use ScriptInterface::CellSystem::CellSystem as a guide.