For developers

Miscellaneous information and tips for navigating and further developing the QMol-grid package.

QMol-grid package structure

For readability, the QMol-grid package is divided into three main components

• Kernel classes, which perform high-level operations (e.g., agnostic of the dimension or discretization). These classes are shared between the deployment of the QMol-grid package in various dimensions.
• Implementation classes, which handle all the computations specific to the 1D QMol-grid version.
• Unit test classes, which perform low-level checks on the methods

When implementing new classes, one should

• have the name of the class start with QMol_; for instance this is required for support in the test suite (i.e., implementing a suite of unit test for the new class)
• derive the class from QMol_suite (abstract handle class); this will (i) provide default set, reset, clear, and constructor and (ii) grant setAccess to many class properties throughout the QMol package.

Class properties

Most components (classes) in the QMol-grid package define both a long and short names for their properties. The long name is for enhanced clarity for end users while their short alternative is intended for readability of the source code. Throughout the QMol-grid package, short names are the ones attached to the class (but hidden) while their longer alternative are (visible but) defined as transient and modify their associated short-name property via set and get method following the template:

properties (Hidden,GetAccess=public,SetAccess=?QMol_suite)
    prop
end
properties (Dependent,GetAccess=public,SetAccess=?QMol_suite)
    longNameProperty                % rho
end
methods
    function val = get.longNameProperty(obj),   val         =   obj.prop;   end
    function set.longNameProperty(obj,val),     obj.prop    =   val;        end
end

Methods in the QMol-grid package should always use the short-name properties, to avoid the overhead associated with the set/get access of their long name alternatives. The QMol-grid package documentation lists properties long names together with the short-hand alternative between parentheses.

Core components

A handful of core component provide unified features and support throughout the QMol-grid package:

• QMol_suite is the foundation for the QMol-grid package. Aside from unit tests, all classes (should) derive from it. It is an abstract handle class and provides default set, reset, clear, and constructor.

Documentation and references

To be listed in the list of components in the QMol-grid package (using the command QMol_doc.showComponents), classes should include the following methods

methods (Static,Access=private)
function version
    QMol_doc.showVersion('##.##.###','##/##/##','Author')
end
end
methods (Static,Access={?QMol_doc,?QMol_myClass})
function showInfo
    fprintf('  * QMol_myClass:\n      > what it does\n'); 
    QMol_myClass.version;
end
end

• QMol_myClass is the name of the class (or the name of the parent class when overloading an existing one)
• In the QMol_doc.showVersion, the entries respectively correspond to the version number, last-modified date, and author
• If the new class is part of QMol-grid's kernel, its name must be added to QMol_doc's showComponents method
• If the new class is part of QMol-grid's implementation, its name must be added to the QMol_info's showComponents method

To implement a class-specific run-time documentation with cited reference handling, see the QMol_doc documentation page.

All run-time documentation and display are set with a 74-character maximum width.

Test suite

All components (classes) in the QMol-grid package should define a test-suite units (even if not tests are to be performed). See the QMol_test documentation page for more details.