QMol_suite

Parent class for all QMol-grid objects.

Description

QMol_suite defines an abstract class from which all objects in the QMol-grid package derive. It provides unified interface and support for parameter (re)initialization. Many classes in the QMol-grid package also restrict set access for their properties to QMol_suite objects (SetAccess=?QMol_suite).

Class properties

isInitialized (isInit)

Throughout the QMol-grid package, this logical flag is used to track whether the object is properly initialized for simulations. Normally, isInitialized is set to a true value after successfully running the initialize method of the class, and back to its default false after creation or running either of the set, reset, or clear methods.

Class methods

Creation

default constructor

Classes overloading QMol_suite inherit a default case-insensitive name-value pair constructor

obj = QMol_child_class(name1,value1);
obj = QMol_child_class(name1,value1,name2,value2,___);

The list of allocatable properties is specified in the propertyNames method that each child class must overload.

Changing class properties

Classes overloading QMol_suite also inherit various methods to interface with properties.

set

Update the name properties of a child-class object to the specified value. Several name-value pairs can be specified consecutively. Suitable name are specified in the propertyNames method and are case insensitive.

obj.set(name1,value1);
obj.set(name1,value1,name2,value2,___);

The set method also reset the class. After running, the set property updates the isInitialized flag to a false value.

reset

Reset the object and update the isInitialized flag to a false.

obj.reset;

Default reset only updates the isInitialized flag. Overloaded reset methods can call the parent default feature following the template

methods (Access=public)
function reset(obj)
%reset the object
    
    % Run parent reset (updates isInit)
    reset@QMol_TDDFT(obj);

    % Add all object-specific reset computations here
end
end

clear

Clear all class properties (specifically all properties listed in the propertyNames method)

obj.clear;

Clear a specific set of the class properties. Suitable name are specified in the propertyNames method and are case insensitive.

obj.clear(name1,name2,___);

The clear method also reset the class. The clear method can be used to delete specific properties before saving an instance of the child class.

The clear method only deletes the specified properties without performing any default-value reinitialization. For that, one should overload the method following the template

methods (Access=public)
function clear(obj,varargin)
%clear clears all or selected member properties
    
    % Run parent clear
    clear@QMol_suite(obj,varargin{:});

    % Add all object-specific clear computations here
end
end

Overloading the class

propertyNames

To enable name-value pair constructor, name-value pair set, and the clear methods, each child class of QMol_suite must overload the propertyNames method following the template

methods (Static=true,Access=?QMol_suite)
function [ClassName,PropNames] = propertyNames()
%propertyNames returns the names of member properties that can be set
%   through name-value assignment
    
    ClassName           =   'QMol_child_class';
    PropNames           =   {'property1','property2'};
end
end

The output ClassName is a string matching the name of the class object. It is used in the constructor, set, and the clear methods if a name property cannot be identified.

The output PropNames is a cell of string containing the list of the member properties that can be allocated as name-value pairs in the constructor and set, and cleared. All of the allocatable properties listed in PropNames must grant setAccess right to QMol_suite classes

properties (___,SetAccess=?QMol_suite)

If overloading the class that already defines a set of allocatable and clearable properties, one can automatically collect these using the template

methods (Static=true,Access=?QMol_suite)
function [ClassName,PropNames] = propertyNames()
%propertyNames returns the names of member properties that can be set
%   through name-value assignment
    
    % Parent-class components
    [~,PropNames]       =   QMol_parent_class.propertyNames;

    ClassName           =   'QMol_child_class';
    PropNames           =   [PropNames,{'property1','property2'}];
end
end

Test suite

For consistency with the rest of the QMol-grid package, QMol_suite defines an associated test suite. Run the test suite for the class in normal or summary mode respectively with

QMol_test.test('suite');
QMol_test.test('-summary','suite');

See QMol_test for details regarding how to create a test suite for new classes.

Notes

• QMol_suite was introduced in version 01.00.
• Version 01.10 moved the run-time documentation components to QMol_doc.