System class design

Table of Contents

• Design patterns
• Adding new components

Design patterns

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.

Adding new components

To add a new feature, the following steps are required:

• core:
  • Store the feature source code in a subfolder. e.g. src/core/feature.
  • Forward-declare the class at the top of src/core/system/System.hpp.
  • Include the relevant header in src/core/system/System.impl.hpp.
  • Adapt the System::System::System constructor accordingly.
• script interface:
  • Define the ScriptInterface class of the new feature, which serves as the connection between the C++ core instance and the Python instance.
  • If relevant, override ScriptInterface::System::Leaf::on_bind_system and ScriptInterface::System::Leaf::on_detach_system.
  • Adapt the ScriptInterface::System::System::System constructor.
  • Adapt the ScriptInterface::System::System::Leaves container.
• Python interface:
  • create a new Python file, e.g. src/python/espressomd/feature.py.
  • Adapt 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.