SimSoup Design: Molecular Structure Module

Modules: Molecular Structure

Module Purpose

The Molecular Structure module represents the structure of Molecule Types in terms of the constituent Atom Types. Molecular structure is represented in two ways, Board Structure and (text) String Structure - see below for details. The module also includes classes that can Join or Split molecular structures.

Class Diagrams

The diagrams below shows the classes that form the Molecular Structure module. The first diagram shows the data relationships between classes (there are no inheritance relationships). The second diagram shows the dependencies between classes.

Data View

Molecular Structure Subsystem
Data Diagram

Dependency View

Molecular Structure Subsystem
Dependency Diagram

Class Descriptions

The classes that are included in the Molecular Structure module, and their definitions, are as follows:-

Atom Type: Represents a type of atom, including its mass, atomic number, and valence properies that affect the way an atom of the type can bond with other atoms.
Board Structure: This class represents the structure of a Molecule Type as a two dimensional rigid structure built from Atoms that are bonded together such that they occupy fixed positions on a square 'Board (similar to a chess board). Each square may contain at most one Atom. Bond angles are always 90° or 180°, and bond lengths are all equal.
Bond Type: This class maintains and makes available information about bond energies and the maximum number of bonds that can be supported by each Atom Type.
Checked Construction Id: This data structure exists solely for performance optimisation in the C++ implementation. It is part of the Molecule Type Joiner class, and is used to record which pairs of Molecule Types have been checked to see whether they can join in a Construction interaction.
Molecule Type Joiner: This class provides functionality that attempts to join two molecular structures, and provides the new structure if one is feasible.
Molecule Type Splitter: This class provides functionality that splits a molecular structure, breaking the bonds along a 'least energy cut'. The class uses the techniques of graph theory, and uses the Dijkstra shortest path algorithm as implemented by the Boost Graph Library.
Molecule Type Splitter API: This is a feature of the C++ implementation. It is a wrapper for the Molecule Type Splitter, providing an interface that avoids the need for user classes to have visibility of the class implementation and the Boost library, thereby simplifying dependencies.

Explanation of Class Data Relationships

The many to many relationship between Atom Type and Board Structure has two aspects:

A Board Structure includes Atom Types. That is, each square in the board can include an Atom Type; at least one square must include an Atom Type. Note that the same Atom Type can occur in multiple squares (just as a 'real' molecule can include, for example, many carbon atoms).
An Atom Type can be included in (multiple) Board Structures (just as in 'real' chemistry, many molecular species can include carbon).

The Molecule Type Joiner has checked MolType as Reactant 1 / Reactant 2 for Construction relationships are used for optimisation. They indicate which pairs of Molecule Types have been checked by the Molecule Type Joiner to see whether they can join in a Construction. In the C++ implementation, the Molecule Type Joiner stores a pair of pointers to Molecule Type for each reactant pair checked.

The Molecule Type has Board Structure and Molecule Type has String Structure relationships associate each Molecule Type with the Board and String representations of its structure.