Package: atomistics
atomistics - Interfaces for atomistic simulation codes and workflowsTheatomisticspackage consists of two primary components. On the one hand it provides interfaces to atomistic
simulation codes - namedcalculators. The supported simulation codes in alphabetical order are:Abinit- Plane wave density functional theoryEMT- Effective medium theory potentialGPAW- Density functional theory Python code based on the projector-augmented wave methodLAMMPS- Molecular DynamicsQuantum Espresso- Integrated suite of Open-Source computer codes for electronic-structure calculationsSiesta- Electronic structure calculations and ab initio molecular dynamicsFor majority of these simulation codes theatomisticspackage use theAtomic Simulation Environmentto interface the underlying C/ C++ and Fortran Codes with the Python programming language. Still this approach limits
the functionality of the simulation code to calculating the energy and forces, so by adding custom interfaces theatomisticspackage can support built-in features of the simulation code like structure optimization and molecular
dynamics.On the other hand theatomisticspackage also providesworkflowsto calculate material properties on the atomistic
scales, these include:Equation of State- to calculate equilibrium properties like the equilibrium energy, equilibrium volume, equilibrium bulk modulus and its pressure derivative.Elastic Matrix- to calculate the elastic constants and elastic moduli.Harmonic and Quasi-harmonic Approximation- to calculate the density of states, vibrational free energy and thermal expansion based on the finite displacements method implemented inphonopy.Molecular Dynamics- to calculate finite temperature properties like thermal expansion including the anharmonic contributions.All theseworkflowscan be coupled with all the simulation codes implemented in theatomisticspackage.
In contrast to theAtomic Simulation Environmentwhich provides similar functionality
the focus of theatomisticspackage is not to reimplement existing functionality but rather simplify the process
of coupling existing simulation codes with existing workflows. Here thephonopyworkflow is a great example to enable the calculation of thermodynamic properties with the harmonic and quasi-harmonic
approximation.ExampleUse the equation of state to calculate the equilibrium properties like the equilibrium volume, equilibrium energy,
equilibrium bulk modulus and its derivative using theGPAWsimulation codefrom ase.build import bulk
from atomistics.calculators import evaluate_with_ase
from atomistics.workflows import EnergyVolumeCurveWorkflow
from gpaw import GPAW, PW

workflow = EnergyVolumeCurveWorkflow(
    structure=bulk("Al", a=4.05, cubic=True),
    num_points=11,
    fit_type='polynomial',
    fit_order=3,
    vol_range=0.05,
    axes=['x', 'y', 'z'],
    strains=None,
)
task_dict = workflow.generate_structures()
print(task_dict)
>>> {'calc_energy': OrderedDict([
>>>     (0.95, Atoms(symbols='Al4', pbc=True, cell=[3.9813426685908118, 3.9813426685908118, 3.9813426685908118])),
>>>     (0.96, Atoms(symbols='Al4', pbc=True, cell=[3.9952635604153612, 3.9952635604153612, 3.9952635604153612])),
>>>     (0.97, Atoms(symbols='Al4', pbc=True, cell=[4.009088111958974, 4.009088111958974, 4.009088111958974])),
>>>     (0.98, Atoms(symbols='Al4', pbc=True, cell=[4.022817972936038, 4.022817972936038, 4.022817972936038])),
>>>     (0.99, Atoms(symbols='Al4', pbc=True, cell=[4.036454748321015, 4.036454748321015, 4.036454748321015])),
>>>     (1.0, Atoms(symbols='Al4', pbc=True, cell=[4.05, 4.05, 4.05])),
>>>     (1.01, Atoms(symbols='Al4', pbc=True, cell=[4.063455248345461, 4.063455248345461, 4.063455248345461])),
>>>     (1.02, Atoms(symbols='Al4', pbc=True, cell=[4.076821973718458, 4.076821973718458, 4.076821973718458])),
>>>     (1.03, Atoms(symbols='Al4', pbc=True, cell=[4.0901016179023415, 4.0901016179023415, 4.0901016179023415])),
>>>     (1.04, Atoms(symbols='Al4', pbc=True, cell=[4.1032955854717175, 4.1032955854717175, 4.1032955854717175])),
>>>     (1.05, Atoms(symbols='Al4', pbc=True, cell=[4.1164052451001565, 4.1164052451001565, 4.1164052451001565]))
>>> ])}In the first step theEnergyVolumeCurveWorkflowobject is initialized including all the parameters to generate
the strained structures and afterwards fit the resulting energy volume curve. This allows the user to see all relevant
parameters at one place. After the initialization the functiongenerate_structures()is called without any
additional parameters. This function returns the task dictionarytask_dictwhich includes the tasks which should
be executed by the calculator. In this case the task is to calculate the energycalc_energyof the eleven
generated structures. Each structure is labeled by the ratio of compression or elongation. In the second step thetask_dictis evaluate with theGPAWsimulation code using theevaluate_with_ase()function:result_dict = evaluate_with_ase(
    task_dict=task_dict,
    ase_calculator=GPAW(
        xc="PBE",
        mode=PW(300),
        kpts=(3, 3, 3)
    )
)
print(result_dict)
>>> {'energy': {
>>>     0.95: -14.895378072824752,
>>>     0.96: -14.910819737657118,
>>>     0.97: -14.922307241122466,
>>>     0.98: -14.930392279321056,
>>>     0.99: -14.935048569964911,
>>>     1.0: -14.936666396364169,
>>>     1.01: -14.935212782128556,
>>>     1.02: -14.931045138839849,
>>>     1.03: -14.924165445706581,
>>>     1.04: -14.914703574005678,
>>>     1.05: -14.902774559134226
>>> }}In analogy to thetask_dictwhich defines the tasks to be executed by the simulation code theresult_dictsummarizes the results of the calculations. In this case the energies calculated for the specific strains. By ordering
both thetask_dictand theresult_dictwith the same labels, theEnergyVolumeCurveWorkflowobject
is able to match the calculation results to the corresponding structure. Finally, in the third step theanalyse_structures()function takes theresult_dictas an input and fits the Equation of State with the fitting parameters defined in
the first step:fit_dict = workflow.analyse_structures(output_dict=result_dict)
print(fit_dict)
>>> {'poly_fit': array([-9.30297838e-05,  2.19434659e-02, -1.68388816e+00,  2.73605421e+01]),
>>>  'fit_type': 'polynomial',
>>>  'fit_order': 3,
>>>  'volume_eq': 66.44252286131888,
>>>  'energy_eq': -14.93670322204575,
>>>  'bulkmodul_eq': 72.38919826304497,
>>>  'b_prime_eq': 4.45383655040775,
>>>  'least_square_error': 4.432974529908853e-09,
>>>  'volume': [63.10861874999998, 63.77291999999998, ..., 69.75163125000002],
>>>  'energy': [-14.895378072824752, -14.910819737657118, ..., -14.902774559134226]
>>> }As a result the equilibrium parameters are returned plus the parameters of the polynomial and the set of volumes and
energies which were fitted to achieve these results. The important step here is that while the interface between the
first and the second as well as between the second and the third step is clearly defined independent of the specific
workflow, the initial parameters for the workflow to initialize theEnergyVolumeCurveWorkflowobject as well as
the final output of thefit_dictare workflow specific.DisclaimerWhile we try to develop a stable and reliable software library, the development remains a opensource project under the
BSD 3-Clause License without any warranties:BSD 3-Clause License

Copyright (c) 2023, Jan Janssen
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.DocumentationInstallationconda-based Installationpypi-based InstallationSimulation CodesASELAMMPSQuantum EspressoWorkflowsElastic MatrixEnergy Volume CurveMolecular DynamicsHarmonic ApproximationStructure OptimizationMaterials PropertiesElastic PropertiesThermal ExpansionHelmholtz Free EnergyPhase DiagramModule Index