Designing the Cap Class

This page describes the design of the Cap class.

What is the Cap class?

The Cap class is responsible for storing the information associated with a nucleus (or set of nuclei) which have been added to a fragment to fix a broken bond. See What is a Cap? for more detail.

Why do we need the Cap class?

The need for the Cap class was motivated by the architectural consideration new state. In short, caps added to complete severed bonds contain more state than the Nucleus objects in the cap and a new class is warranted.

Cap class considerations

new objects: Caps typically are placed in locations in space where no supersystem object resides (they usually are not placed directly where the replaced object resided). This means that the caps will have to be treated as new objects since they are not actually present in the target supersystem.

replaced type: When we fragment an object of type Nuclei we break bonds between Nucleus objects. The cap we add to fix this bond will have state consistent with a Nucleus object (or more generally a Nuclei object, vide infra).

bond memory: It is important for a cap to remember what object it replaced and what object it is bonded to.

multiple objects: Caps are usually monovalent. They also are usually comprised of a single center; however, this is not always the case. In general the caps needed for breaking up Nuclei objects will also be Nuclei objects.

Out of Scope

electrons: We treat caps purely as nuclei. The motivation is that typically users assign the number of electrons and multiplicity to the capped system, i.e., electrons are not individually added to the uncapped system and then the caps.

Capping Classes Design

Each Cap object knows the identity of the anchor object, the identity of the replaced object, and the nuclei forming the cap. This satisfies the bond memory and multiple objects considerations. Finally, to satisfy new objects each Cap holds a Nuclei object for the new nucleus or nuclei.

Caps Design Summary

new objects: Each Cap object holds the object(s) used to cap the broken bond.
replaced type: Cap objects replace Nucleus objects, not Atom objects, i.e., they do not include electrons.
bond memory: The Cap object holds the indices of the anchor and replaced objects in addition to the literal state of the cap.
multiple objects: Each Cap object can contain multiple Nucleus objects.