.. role:: raw-html-m2r(raw) :format: html MAISE library interface ======================= General interface function -------------------------- MAISE functions can be called from external Fortan, C, or C++ codes. The main routine that can be called from external codes is CALL_MAISE(). This is an interface function that returns the enthalpy, forces, and stresses calculated with the neural network (NN) or traditional interatomic potential specified in the ``model`` file. The input and output variables are explained below, followed by examples of how the function can be called from basic Fortran, C, and C++ codes. .. literalinclude:: ./file/cmod.c :language: C Interface program examples -------------------------- Examples of basic Fortran, C, and CPP interface programs can be found here. + `Fortran `_ + `C `_ + `CPP `_ The interface code will call MAISE to calculate force components and energy for a small nanoparticle using the provided NN model. In order to compile and test the interface program for the desired language (xx = f90, c, or cpp), you should: + download and install MAISE, which will save ``libmaise.a`` in the installation directory + go to the directory for the desired language (xx = f90, c, or cpp) + set 'M_LIB' in the makefile to the directory with installed MAISE + compile the interface code by running ``make`` + go to ``./bin`` and run ``xx2maise``. .. note:: The initialization of the NN is quite expensive, so it is done only once upon the first CALL_MAISE() call. For this reason, the relevant MAISE structures (ANN, LNK, etc.) are declared in the external code, so that they can be reused in subsequent calls. LAMMPS interface ---------------- MAISE-LAMMPS adds the MAISE-based NN interaction description to the list of LAMMPS potential types. Once the interface is installed, a user can run LAMMPS standard simulation jobs (molecular dynamics, local optimization, etc.) during which MAISE is called to evaluate the interatomic interactions (energy/enthalpy, forces, and stresses) using a NN specified in ``model``. Installation ^^^^^^^^^^^^ If you already have LAMMPS, MAISE-LAMMPS can be installed as follows: .. code-block:: bash cd lammps/src git clone https://github.com/maise-guide/maise-lammps.git MAISE; make -C MAISE If you do not have LAMMPS, please follow these steps: .. code-block:: bash git clone https://github.com/lammps/lammps.git cd lammps/src git clone https://github.com/maise-guide/maise-lammps.git MAISE make yes-maise make mpi --jobs If you wish to remove MAISE from LAMMPS and remove all MAISE files, please run: .. code-block:: bash cd lammps/src make no-MAISE rm -rf MAISE Setup ^^^^^ A baseline knowledge of LAMMPS is assumed for users of MAISE-LAMMPS. As usual, the user needs a LAMMPS data file defining the structure and a LAMMPS input script specifying the simulation. In addition, the user needs a MAISE ``model`` file defining the specific interaction description (a NN or a traditional potential). MAISE model ~~~~~~~~~~~ A MAISE ``model`` can be obtained from the ``models/`` directory in the MAISE distribution package. Typical ``model`` files are provided in the examples directories below. LAMMPS data file ~~~~~~~~~~~~~~~~ A standard LAMMPS data file should be used. The only requirement is that atoms appear in the increasing order of their atomic numbers as in the ``model`` file. Here is an example of a periodic Sn diamond structure: .. literalinclude:: ./file/data.crystal .. note:: The number of atom types is set to 2 because the NN ``model`` in this example corresponds to the Li-Sn binary system. The structure is pure Sn because all atom types are set to 2. A similar convention should be used for systems with more species. LAMMPS input file ~~~~~~~~~~~~~~~~~ Detailed information about LAMMPS standard simulation settings can be found on `LAMMPS wiki `_. The table below gives the full list of commands that may have specific settings to define MAISE-LAMMPS runs. .. list-table:: Table 1: Modified Commands :header-rows: 1 * - COMMAND - Short Description * - `units <#units0>`_ - sets units (must be set to `metal`) * - `boundary <#bound0>`_ - sets boundary conditions (either `f f f` or `p p p`) * - `atom_style <#atoms0>`_ - declares the atom style LAMMPS will use (must be set to `atomic`) * - `mass <#mass0>`_ - sets the masses of each species (in the same order as in the model file) * - `pair_style <#pairs0>`_ - declares the pair style for the run of LAMMPS (must be set to `maise`) * - `compute <#comp0>`_ - declares the compute style (must be `maisestress`) * - `thermo_modify <#ther0>`_ - modifies thermo to use MAISE stresses (see syntax below) * - `fix_modify <#fixm0>`_ - modifies fix to use MAISE stresses (see syntax below) .. _units0: **units** sets the units for the run of LAMMPS. It should always be set to `metal` for a run of MAISE-LAMMPS. Namely: .. code-block:: bash units metal .. _bound0: **boundary** sets either periodic or fixed boundaries. Currently, MAISE treats structures as either nonperiodic or periodic in all three dimensions. So, if a structure has `any` periodic boundaries then `all` boundaries must be set to periodic: .. code-block:: bash boundary p p p .. _atoms0: **atom_style** sets atom style for the run of LAMMPS. It must be `atomic` for MAISE-LAMMPS: .. code-block:: bash atom_style atomic .. _mass0: **mass** sets the masses for `all` species in the `same` order they appear in the MAISE ``model`` file. For example: .. code-block:: bash mass 1 6.941 mass 2 118.71 .. _pairs0: **pair_style** declares the pair style for the run of LAMMPS. The first argument must be `maise` in order to use MAISE-LAMMPS. The second argument must be the cutoff distance for each atom in angstroms, which can be found at the end of the ``model`` file (see `here `__ for more details). The third argument is the number of cores for parallelization, which should be a factor of the total number of atoms. For example: .. code-block:: bash pair_style maise 7.5 4 .. _comp0: **compute** declares a compute style for a particular value for the run of LAMMPS. In MAISE-LAMMPS, the compute style `maisestress` is used to pass the stress tensor from MAISE to LAMMPS. The first argument is the compute ID which will be used in the modify commands. .. code-block:: bash compute press_ID all maisestress thermo_temp .. _fixm0: **fix_modify** modifies a fix to use MAISE stresses. For example: .. code-block:: bash fix_modify fix_ID energy no virial no press press_ID Please see the example scripts in ``src/MAISE/examples/`` for basic structure relaxations. Execution ^^^^^^^^^ The standard command is used to run MAISE-LAMMPS jobs. The user should either make the ``lmp_mpi`` executable globally available or use a specific path to the executable to run it. An input ``script`` file, such as ``in.crystal`` or ``in.cluster`` shown below, should be passed to LAMMPS as follows: .. code-block:: bash lmp_mpi -in script Examples ^^^^^^^^ Crystal relaxation ~~~~~~~~~~~~~~~~~~ An example of a full crystal structure relaxation at 10 GPa (100 kB) is given in ``MAISE/examples/relax-crystal`` , with the following ``in.crystal`` input file: .. literalinclude:: ./file/in.crystal The job should be run in the example directory: .. code-block:: bash cd lammps/src; cd MAISE/examples/relax-crystal ../../../lmp_mpi -in in.crystal .. note:: If a crystal minimization stops before reaching the energy tolerance and has the stopping criteria "linesearch alpha is zero", tweaking the value `vmax` in `fix box/relax` may help. This is not a MAISE-LAMMPS exclusive fix, but it is worthy of note. Cluster relaxation ~~~~~~~~~~~~~~~~~~ An example of a nonperiodic cluster relaxation is given in ``MAISE/examples/relax-cluster`` , with the following ``in.cluster`` input file: .. literalinclude:: ./file/in.cluster The job should be run in the example directory: .. code-block:: bash cd lammps/src; cd MAISE/examples/relax-cluster ../../../lmp_mpi -in in.cluster .. note:: As usual, `fix box/relax` is not required for nonperiodic structure relaxations.