ase.calculators.calculator — ASE documentation

### Navigation

- index
- modules |
- Module code »
- ase.calculators »

# Source code for ase.calculators.calculator

    import os
    import copy
    import subprocess
    from math import pi, sqrt

    import numpy as np

    class ReadError(Exception):
        pass

    all_properties = ['energy', 'forces', 'stress', 'dipole',
                      'charges', 'magmom', 'magmoms']

    all_changes = ['positions', 'numbers', 'cell', 'pbc',
                   'initial_charges', 'initial_magmoms']

    # Recognized names of calculators sorted alphabetically:
    names = ['abinit', 'aims', 'asap', 'castep', 'cp2k', 'dftb', 'eam', 'elk',
             'emt', 'exciting', 'fleur', 'gaussian', 'gpaw', 'gromacs', 'hotbit',
             'jacapo', 'lammps', 'lammpslib', 'lj', 'mopac', 'morse',
             'nwchem', 'siesta', 'turbomole', 'vasp']

    special = {'cp2k': 'CP2K',
               'eam': 'EAM',
               'elk': 'ELK',
               'emt': 'EMT',
               'fleur': 'FLEUR',
               'lammps': 'LAMMPS',
               'lammpslib': 'LAMMPSlib',
               'lj': 'LennardJones',
               'morse': 'MorsePotential',
               'nwchem': 'NWChem'}

    def get_calculator(name):
        """Return calculator class."""
        if name == 'asap':
            from asap3 import EMT as Calculator
        elif name == 'gpaw':
            from gpaw import GPAW as Calculator
        elif name == 'hotbit':
            from hotbit import Calculator
        else:
            classname = special.get(name, name.title())
            module = __import__('ase.calculators.' + name, {}, None, [classname])
            Calculator = getattr(module, classname)
        return Calculator

    def equal(a, b, tol=None):
        """ndarray-enabled comparison function."""
        if isinstance(a, np.ndarray):
            b = np.array(b)
            if a.shape != b.shape:
                return False
            if tol is None:
                return (a == b).all()
            else:
                return np.allclose(a, b, rtol=tol, atol=tol)
        if isinstance(b, np.ndarray):
            return equal(b, a, tol)
        if tol is None:
            return a == b
        return abs(a - b) < tol * abs(b) + tol

    def kptdensity2monkhorstpack(atoms, kptdensity=3.5, even=True):
        """Convert k-point density to Monkhorst-Pack grid size.

        atoms: Atoms object
            Contains unit cell and information about boundary conditions.
        kptdensity: float
            Required k-point density.  Default value is 3.5 point per Ang^-1.
        even: bool
            Round up to even numbers.
        """

        recipcell = atoms.get_reciprocal_cell()
        kpts = []
        for i in range(3):
            if atoms.pbc[i]:
                k = 2 * pi * sqrt((recipcell[i]**2).sum()) * kptdensity
                if even:
                    kpts.append(2 * int(np.ceil(k / 2)))
                else:
                    kpts.append(int(np.ceil(k)))
            else:
                kpts.append(1)
        return np.array(kpts)

    def kpts2mp(atoms, kpts, even=False):
        if kpts is None:
            return np.array([1, 1, 1])
        if isinstance(kpts, (float, int)):
            return kptdensity2monkhorstpack(atoms, kpts, even)
        else:
            return kpts

    class Parameters(dict):
        """Dictionary for parameters.

        Special feature: If param is a Parameters instance, then param.xc
        is a shorthand for param['xc'].
        """

        def __getattr__(self, key):
            if key not in self:
                return dict.__getattribute__(self, key)
            return self[key]

        def __setattr__(self, key, value):
            self[key] = value

        @classmethod
        def read(cls, filename):
            """Read parameters from file."""
            file = open(os.path.expanduser(filename))
            parameters = cls(eval(file.read()))
            file.close()
            return parameters

        def tostring(self):
            keys = sorted(self.keys())
            return 'dict(' + ',\n     '.join(
                '%s=%r' % (key, self[key]) for key in keys) + ')\n'

        def write(self, filename):
            file = open(filename, 'w')
            file.write(self.tostring())
            file.close()

    class Calculator:
        """Base-class for all ASE calculators.

        A calculator must raise NotImplementedError if asked for a
        property that it can't calculate.  So, if calculation of the
        stress tensor has not been implemented, get_stress(atoms) should
        raise NotImplementedError.  This can be achieved simply by not
        including the string 'stress' in the list implemented_properties
        which is a class member.  These are the names of the standard
        properties: 'energy', 'forces', 'stress', 'dipole', 'charges',
        'magmom' and 'magmoms'.
        """

        implemented_properties = []
        'Properties calculator can handle (energy, forces, ...)'

        default_parameters = {}
        'Default parameters'

        def __init__(self, restart=None, ignore_bad_restart_file=False, label=None,
                     atoms=None, **kwargs):
            """Basic calculator implementation.

            restart: str
                Prefix for restart file.  May contain a directory.  Default
                is None: don't restart.
            ignore_bad_restart_file: bool
                Ignore broken or missing restart file.  By default, it is an
                error if the restart file is missing or broken.
            label: str
                Name used for all files.  May contain a directory.
            atoms: Atoms object
                Optional Atoms object to which the calculator will be
                attached.  When restarting, atoms will get its positions and
                unit-cell updated from file.
            """

            self.atoms = None  # copy of atoms object from last calculation
            self.results = {}  # calculated properties (energy, forces, ...)
            self.parameters = None  # calculational parameters

            if restart is not None:
                try:
                    self.read(restart)  # read parameters, atoms and results
                except ReadError:
                    if ignore_bad_restart_file:
                        self.reset()
                    else:
                        raise

            self.label = None
            self.directory = None
            self.prefix = None

            self.set_label(label)

            if self.parameters is None:
                # Use default parameters if they were not read from file:
                self.parameters = self.get_default_parameters()

            if atoms is not None:
                atoms.calc = self
                if self.atoms is not None:
                    # Atoms were read from file.  Update atoms:
                    if not (equal(atoms.numbers, self.atoms.numbers) and
                            (atoms.pbc == self.atoms.pbc).all()):
                        raise RuntimeError('Atoms not compatible with file')
                    atoms.positions = self.atoms.positions
                    atoms.cell = self.atoms.cell

            self.set(**kwargs)

            if not hasattr(self, 'name'):
                self.name = self.__class__.__name__.lower()

        def set_label(self, label):
            """Set label and convert label to directory and prefix.

            Examples:

            * label='abc': (directory='.', prefix='abc')
            * label='dir1/abc': (directory='dir1', prefix='abc')

            Calculators that must write results to files with fixed names
            can overwrite this method so that the directory is set to all
            of label."""

            self.label = label

            if label is None:
                self.directory = None
                self.prefix = None
            else:
                self.directory, self.prefix = os.path.split(label)
                if self.directory == '':
                    self.directory = os.curdir

        def get_default_parameters(self):
            return Parameters(copy.deepcopy(self.default_parameters))

        def todict(self):
            default = self.get_default_parameters()
            return dict((key, value)
                        for key, value in self.parameters.items()
                        if key not in default or value != default[key])

        def reset(self):
            """Clear all information from old calculation."""

            self.atoms = None
            self.results = {}

        def read(self, label):
            """Read atoms, parameters and calculated properties from output file.

            Read result from self.label file.  Raise ReadError if the file
            is not there.  If the file is corrupted or contains an error
            message from the calculation, a ReadError should also be
            raised.  In case of succes, these attributes must set:

            atoms: Atoms object
                The state of the atoms from last calculation.
            parameters: Parameters object
                The parameter dictionary.
            results: dict
                Calculated properties like energy and forces.

            The FileIOCalculator.read() method will typically read atoms
            and parameters and get the results dict by calling the
            read_results() method."""

            self.set_label(label)

        def get_atoms(self):
            if self.atoms is None:
                raise ValueError('Calculator has no atoms')
            atoms = self.atoms.copy()
            atoms.calc = self
            return atoms

        @classmethod
        def read_atoms(cls, restart, **kwargs):
            return cls(restart=restart, label=restart, **kwargs).get_atoms()

        def set(self, **kwargs):
            """Set parameters like set(key1=value1, key2=value2, ...).

            A dictionary containing the parameters that have been changed
            is returned.

            Subclasses must implement a set() method that will look at the
            chaneged parameters and decide if a call to reset() is needed.
            If the changed parameters are harmless, like a change in
            verbosity, then there is no need to call reset().

            The special keyword 'parameters' can be used to read
            parameters from a file."""

            if 'parameters' in kwargs:
                filename = kwargs.pop('parameters')
                parameters = Parameters.read(filename)
                parameters.update(kwargs)
                kwargs = parameters

            changed_parameters = {}

            for key, value in kwargs.items():
                oldvalue = self.parameters.get(key)
                if key not in self.parameters or not equal(value, oldvalue):
                    if isinstance(oldvalue, dict):
                        # Special treatment for dictionary parameters:
                        for name in value:
                            if name not in oldvalue:
                                raise KeyError(
                                    'Unknown subparameter "%s" in '
                                    'dictionary parameter "%s"' % (name, key))
                        oldvalue.update(value)
                        value = oldvalue
                    changed_parameters[key] = value
                    self.parameters[key] = value

            return changed_parameters

        def check_state(self, atoms, tol=1e-15):
            """Check for system changes since last calculation."""
            if self.atoms is None:
                system_changes = all_changes
            else:
                system_changes = []
                if not equal(self.atoms.positions, atoms.positions, tol):
                    system_changes.append('positions')
                if not equal(self.atoms.numbers, atoms.numbers):
                    system_changes.append('numbers')
                if not equal(self.atoms.cell, atoms.cell, tol):
                    system_changes.append('cell')
                if not equal(self.atoms.pbc, atoms.pbc):
                    system_changes.append('pbc')
                if not equal(self.atoms.get_initial_magnetic_moments(),
                             atoms.get_initial_magnetic_moments(), tol):
                    system_changes.append('initial_magmoms')
                if not equal(self.atoms.get_initial_charges(),
                             atoms.get_initial_charges(), tol):
                    system_changes.append('initial_charges')

            return system_changes

        def get_potential_energy(self, atoms=None, force_consistent=False):
            energy = self.get_property('energy', atoms)
            if force_consistent:
                return self.results.get('free_energy', energy)
            else:
                return energy

        def get_forces(self, atoms=None):
            return self.get_property('forces', atoms)

        def get_stress(self, atoms=None):
            return self.get_property('stress', atoms)

        def get_dipole_moment(self, atoms=None):
            return self.get_property('dipole', atoms)

        def get_charges(self, atoms=None):
            return self.get_property('charges', atoms)

        def get_magnetic_moment(self, atoms=None):
            return self.get_property('magmom', atoms)

        def get_magnetic_moments(self, atoms=None):
            return self.get_property('magmoms', atoms)

        def get_property(self, name, atoms=None, allow_calculation=True):
            if name not in self.implemented_properties:
                raise NotImplementedError

            if atoms is None:
                atoms = self.atoms
                system_changes = []
            else:
                system_changes = self.check_state(atoms)
                if system_changes:
                    self.reset()

            if name not in self.results:
                if not allow_calculation:
                    return None
                try:
                    self.calculate(atoms, [name], system_changes)
                except Exception:
                    self.reset()
                    raise

            if name == 'magmom' and 'magmom' not in self.results:
                return 0.0

            if name == 'magmoms' and 'magmoms' not in self.results:
                return np.zeros(len(atoms))

            result = self.results[name]
            if isinstance(result, np.ndarray):
                result = result.copy()
            return result

        def calculation_required(self, atoms, properties):
            system_changes = self.check_state(atoms)
            if system_changes:
                return True
            for name in properties:
                if name not in self.results:
                    return True
            return False

        def calculate(self, atoms=None, properties=['energy'],
                      system_changes=all_changes):
            """Do the calculation.

            properties: list of str
                List of what needs to be calculated.  Can be any combination
                of 'energy', 'forces', 'stress', 'dipole', 'charges', 'magmom'
                and 'magmoms'.
            system_changes: list of str
                List of what has changed since last calculation.  Can be
                any combination of these five: 'positions', 'numbers', 'cell',
                'pbc', 'initial_charges' and 'initial_magmoms'.

            Subclasses need to implement this, but can ignore properties
            and system_changes if they want.  Calculated properties should
            be inserted into results dictionary like shown in this dummy
            example::

                self.results = {'energy': 0.0,
                                'forces': np.zeros((len(atoms), 3)),
                                'stress': np.zeros(6),
                                'dipole': np.zeros(3),
                                'charges': np.zeros(len(atoms)),
                                'magmom': 0.0,
                                'magmoms': np.zeros(len(atoms))}

            The subclass implementation should first call this
            implementation to set the atoms attribute.
            """

            if atoms is not None:
                self.atoms = atoms.copy()

        def calculate_numerical_forces(self, atoms, d=0.001):
            """Calculate numerical forces using finite difference.

            All atoms will be displaced by +d and -d in all directions."""

            from ase.calculators.test import numeric_force
            return np.array([[numeric_force(atoms, a, i, d)
                              for i in range(3)] for a in range(len(atoms))])

        def get_spin_polarized(self):
            return False

    class FileIOCalculator(Calculator):
        """Base class for calculators that write/read input/output files."""

        command = None
        'Command used to start calculation'

        def __init__(self, restart=None, ignore_bad_restart_file=False,
                     label=None, atoms=None, command=None, **kwargs):
            """File-IO calculator.

            command: str
                Command used to start calculation.
            """

            Calculator.__init__(self, restart, ignore_bad_restart_file, label,
                                atoms, **kwargs)

            if command is not None:
                self.command = command
            else:
                name = 'ASE_' + self.name.upper() + '_COMMAND'
                self.command = os.environ.get(name, self.command)

        def calculate(self, atoms=None, properties=['energy'],
                      system_changes=all_changes):
            Calculator.calculate(self, atoms, properties, system_changes)
            self.write_input(self.atoms, properties, system_changes)
            if self.command is None:
                raise RuntimeError('Please set $%s environment variable ' %
                                   ('ASE_' + self.name.upper() + '_COMMAND') +
                                   'or supply the command keyword')
            command = self.command.replace('PREFIX', self.prefix)
            olddir = os.getcwd()
            try:
                os.chdir(self.directory)
                errorcode = subprocess.call(command, shell=True)
            finally:
                os.chdir(olddir)

            if errorcode:
                raise RuntimeError('%s returned an error: %d' %
                                   (self.name, errorcode))
            self.read_results()

        def write_input(self, atoms, properties=None, system_changes=None):
            """Write input file(s).

            Call this method first in subclasses so that directories are
            created automatically."""

            if self.directory != os.curdir and not os.path.isdir(self.directory):
                os.makedirs(self.directory)

        def read_results(self):
            """Read energy, forces, ... from output file(s)."""
            pass

### Navigation

- index
- modules |
- Module code »
- ase.calculators »