QMol_Vmol

Parent class for all molecular-potential objects.

Description

QMol_Vmol defines an abstract class for the description of molecular potentials as sums of atom-like centers (pseudopotentials). It also provides support for compact run-time documentation of the molecular model.

Class properties

Molecular model

atom

Atomic centers in the molecule [ cell (default []) ]

• atom = {V1,V2,___} Where each of the Vs is a compatible atom-like center (pseudopotentials)

Other properties

These properties cannot be edited with the set method.

isInitialized (isInit)

Whether the potential object is properly initialized. This is used throughout the QMol-grid package to check that the potential object holds meaningful information and is ready for use. Changing its isSpinPol may cause simulations to fail or produce erroneous results.

numberAtom (nbA)

Number of atomic centers in the object [ positive integer (default []) ]

• This is defined as numel(atom).
• Un-initialized QMol_DFT_Vext objects, i.e., isInitialized == false , have empty numberAtom.

Class methods

Creation

QMol_doc is an abstract class and cannot be instantiated.

Changing class properties

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

set

QMol_Vmol inherits the name-value assignment for the molecular model properties from QMol_suite.

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;

• This also resets all the atom-like centers in the object, equivalent to the command for k = 1:nbA , atom{k}.reset; end

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_Vmol(obj);

    % Add all object-specific reset computations here
end
end

clear

Clear all molecular model properties

obj.clear;

Clear a specific set of the class properties. Suitable name are specified any of the molecular model properties 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.

Initializing the object

initialize

Initialize a QMol_Vmol object without attaching a QMol-grid theory object and set the isInitialized flag to true.

obj.initialize;
obj.initialize([]);

• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization
• This initializes all the atom-like centers in the object, equivalent to the command for k = 1:nbA , atom{k}.initialize([]); end
• This is only provided for extended compatibility and will likely cause errors in simulations. Initialization with attaching a QMol-grid theory object (next) is recommended.

Initialize a QMol_Vmol object with attaching a QMol-grid theory object

obj.initialize(QM);

• This performs a similar initialization as previously, including reset, but with initializing each of the atom-like centers with the QMol-grid theory object. It is equivalent to the command for k = 1:nbA , atom{k}.initialize(QM); end

Run-time documentation

QMol_Vmol provides support for compact run-time documentation of the molecular model.

showDocumentation

Display the run-time documentation for the specific configuration of a QMol_Vmol object

ref = obj.showDocumentation;

• The output ref is a cell vector containing the list of references to be included in the bibliography.
• The run-time documentation performs the following steps: (1) It call the implementation-specific run-time documentation with the property showDoc. (2) It parses through the atom-like centers listed in atom, and call their run-time documentation to list the specific parameters for each of them. (3) For each type of pseudopotential used, call again the run-time documentation to display their generic description. This ensures a full but compact description of the molecular model without repeating general properties of pseudopotentials that are used several times in the molecular model.

Overloading the class

To define a specific implementation of molecular potential, overloading classes must define the following methods with the specified signature and attributes

propertyNames

To enable name-value pair constructor, name-value pair set, and the clear methods

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_Vmol.propertyNames;

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

showDoc

Display the run-time documentation for the specific implementation of the molecular potential.

methods (Access=?QMol_Vmol)
function ref = showDoc(obj)
%showDoc displays the documentation reflecting the specific implementation
%   of the molecular model
    
    % Add specific documentation here

end
end

• If no reference is cited, return ref = {} otherwise ref = {'ref 1','ref 2',___}, where each of the ref corresponds to the bibliographic code for the reference (generally of the form 'name_of_first_author publication_year') and is case insensitive -- see the documentation page for a list of citable references.

Compatible atom-like center (pseudopotentials) objects

To be compatible with QMol_Vmol, atom-like center (pseudopotentials) classes must define the following properties with the specified signatures

showDocumentation

Signature for the run-time documentation of a pseudopotential

methods (Access=public)
function ref = showDocumentation(obj,opt)
%showDocumentation displays the documentation reflecting member property 
%   values
    
    % Initialization
    if nargin == 1,     opt     =   [];         end
    if isempty(opt),    opt     =   'full';     end

    ref                 =   {};
    
    % Display (appropriate) documentation
    switch lower(opt)
        case {'full','all'}
            % Display both potential shape and parameters

        case {'param','parameters'}
            % Display only the potential ID and parameters
            
            ref         =   'potential_ID';
        case {'pot','potential'}
            % Display the generic description of the potential

        otherwise
            % Throw a warning or error for unexpected call
    end
    
end
end

• The initialization block is not mandatory but ensures that the showDocumentation (i) returns the appropriate output format and (ii) defines a default behavior if the end user calls the run-time documentation on an instance of the pseudopotential object (see also next).
• The case {'full','all'} block is not mandatory but enables extended run-time documentation outside of QMol_Vmol's.
• At minimum, the following two blocks must define 'pot' and 'param' options; the added 'parameters' and 'potential' enable a more user-friendly interface.
• The catch all otherwise block is not mandatory but ensures that unexpected documentation options are flagged.

initialize

Initialized a pseudopotential object with

methods (Access=public)
function initialize(obj,QM)
%initialize initializes the pseudopotential object
    
    % Add the initialization here

    % Update the initialization flag
    obj.isInit       =   true;
end
end

• The input QM is the QMol-grid theory object passed by QMol_Vmol's initialize method.
• If no QMol-grid theory object is required for the initialization, replace the function definition line with function initialize(obj,~)

propertyNames

Same requirements as for QMol_Vmol's propertyNames.

getPotential

Get the discretization of the pseudopotential. The specific signature is dimension dependent

V = obj.getPotential(___);

getPotentialDerivative

Get the discretization of the spatial derivative (gradient) of the pseudopotential. The specific signature is dimension dependent

DV = obj.getPotentialDerivative(___);

Test suite

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

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

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

Notes

• QMol_Vmol was introduced in version 01.00.