Fortran 90 derived-type support

Object oriented interface on top of f2py generated wrappers.

This module adds support for derived types to f2py generated modules, providing the Fortran source code was built using f2py_wrapper_gen.

Module contents for quippy.oo_fortran:

Classes

FortranDerivedType(*args, **kwargs) Abstract base class for all fortran derived types.

Functions

wrap_all(fobj, spec, mods, merge_mods, …) Returns tuple (classes, routines, params) suitable for importing into top-level package namespace.

Attributes

Name Value
FortranDerivedTypes
class quippy.oo_fortran.FortranDerivedType(*args, **kwargs)[source]

Abstract base class for all fortran derived types.

This class is an abstract base class for all Fortran derived-types. It contains all the magic necessary to communicate with a module wrapped using the f2py_wrapper_gen module.

The constructor invokes a Fortran interface or routine to initialise the object. When the reference count for instances of this class drops to zero, the destructor frees the associated Fortran derived type.

Methods

is_same_fortran_object(other) Test if self and other point to the same Fortan object.
shallow_copy() Return a shallow copy of self.
shallow_copy_from(other) Transform self into a shallow copy of other.

Important attributes and methods are as follows:

_fpointer

Pointer to underlying Fortran derived type instrance, or None if not initialised.

_routines

Dictionary mapping routine names to tuples (fortran_object, specification). Used by _runroutine().

_interfaces

Dictionary mapping interface names to a list of 3-tuples (name, specification, fortran_object). Used by _runinterface().

_elements

Dictionary mapping Fortran element names to tuple (get_routine, set_routine). A property is created for each entry in _elements which invokes get_routine and set_routine automatically.

_subobjs

Dictionary mapping names of component objects to tuples (get_routine, set_routine). Used by _update().

_arrays

Dictionary mapping names of arrays to tuples (array_func, doc_string). Used by _update().

_runroutine(name, *args, **kwargs)[source]

Internal method used to invoke the Fortran routine name

name must be a valid key in _routines. Wrapper methods which simply call _runroutine() are automatically generated in subclasses of FortranDerivedType by wrap_all().

Input arguments which are instances of a subclass of FortranDerivedType are replaced by their _fpointer integer attribute.

If there is an keyword argument with the name args_str then unexpected keyword arguments are permitted. All the undefined keyword arguments are collected together to form a dictionary which is converted to string form and used as the the arg_string argument, providing rudimentary support for variable numbers and types of arguments. For example:

p = Potential('IP SW', xml_string)
    p.calc(at, virial=True, energy=True)

is equivalent to:

p = Potential('IP SW', xml_string)
    p.calc(at, args_str="virial energy")

The return value us made up of a tuple of the arguments to the Fortran routine which are intent(out). Pointers to Fortran derived-type instances are replaced with new instances of the appropriate subclass of FortranDerivedType. Arrays are converted to use one-based indexing using FortranArray.

_runinterface(name, *args, **kwargs)[source]

Internal method used to invoke the appropriate routine within the Fortran interface name. If no routine is found matching the names and types of the arguments provided then an TypeError exception is raised.

Arguments and results are handled in the same way as _runroutine().

_update()[source]

Automatically invoked whenever this object needs to be updated. This happens when it is first created, when it is direcly passed to a Fortran routine with intent(in,out) or when it is a component of another object which is passed with intent(in,out).

This method also invokes all the hook in the _update_hooks list. This can be used in subclasses to allow a customised response. For example this mechanism is used in quippy.extras.Atoms to update Atoms properties.

_get_array_shape(name)[source]

This method can be used to override Fortran’s idea of the shape of arrays within derived types, for example to present only a partial view of an array. This is used in quippy.table.Table to allow the sizes of arrays within the Table class to correspond to the current extent of the Table, rather than the size of the allocated storage which will usually be larger.

If this method returns None then the full array is presented, otherwise the return value should be a tuple (N_1, N_2, …, N_d) where d is the number of dimensions of the array and N_1, N_2 etc. are the lengths of each dimension.

is_same_fortran_object(other)[source]

Test if self and other point to the same Fortan object.

shallow_copy()[source]

Return a shallow copy of self.

shallow_copy_from(other)[source]

Transform self into a shallow copy of other.

quippy.oo_fortran.wrap_all(topmod, spec, mods, short_names)[source]

Returns tuple (classes, routines, params) suitable for importing into top-level package namespace. topmod should be an f2py-generated module containing fortran objects, and spec should be the specification dictionary generated by f2py_wrapper_gen.wrap_mod(). mods is a list of the names of Fortran modules to wrap, and short_names is a dictionary mapping shortened Fortran derived-type names to their canonical form.

classes and routines are lists of (name, value) tuples where value is a newly defined subclass of FortranDerivedType or newly wrapped routine respectively. params is a Python dictionary of Fortran parameters (constants).

Here’s how this function is used in quippy’s __init.py__ to import the new classes, routines and params into the top-level quippy namespace:

classes, routines, params = wrap_all(_quippy, spec, spec['wrap_modules'], spec['short_names'])

for name, cls in classes:
   setattr(sys.modules[__name__], name, cls)

for name, routine in routines:
   setattr(sys.modules[__name__], name, routine)

sys.modules[__name__].__dict__.update(params)
quippy.oo_fortran.FortranDerivedTypes

Dictionary mapping Fortran type names in format type(lower_case_name) to classes derived from FortranDerivedType.