1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
.. _aep1:
=============================
Calculator interface proposal
=============================
All ASE calculators should behave similarly if there is no good reason
for them not to. This should make it simpler for both users and developers.
This proposal tries to define how a good ASE calculator should behave.
The goal is to have ASE calculators:
* that share more code
* are more uniform to use
* are better tested
* are portable
Setting some standards is a good thing, but we should also be careful
not to set too strict rules that could limit each calculator to the
lowest common denominator.
Behavior
========
When a calculator calculates the energy, forces, stress tensor, total
magnetic moment, atomic magnetic moments or dipole moment, it should
store a copy of the system (atomic numbers, atomic positions, unit
cell and boundary conditions). When asked again, it should return the
value already calculated if the system hasn't been changed.
If calculational parameters such as plane wave cutoff or XC-functional
has been changed the calculator should throw away old calculated
values.
Standards parameters
====================
The standard keywords that all calculators must use (if they make
sense) are: ``xc``, ``kpts``, ``smearing``, ``charge`` and ``nbands``.
Each calculator will have its own default values for these parameters
--- see recommendations below. In addition, calculators will
typically have many other parameters. The units are eV and Å.
Initial magnetic moments are taken from the :class:`~ase.Atoms`
object.
:xc:
It is recommended that ``'LDA'`` and ``'PBE'`` are valid options.
:kpts:
* ``(1,1,1)``: Gamma-point
* ``(n1,n2,n3)``: Monkhorst-Pack grid
* ``(n1,n2,n3,'gamma')``: Shifted Monkhorst-Pack grid that includes `\Gamma`
* ``[(k11,k12,k13),(k21,k22,k23),...]``: Explicit list in units of the
reciprocal lattice vectors
* ``kpts=3.5``: `\vec k`-point density as in 3.5 `\vec k`-points per
Å\ `^{-1}`
:smearing:
The smearing parameter must be given as a tuple:
* ``('Fermi-Dirac', width)``
* ``('Gaussian', width)``
* ``('Methfessel-Paxton', width, n)``, where `n` is the order (`n=0`
is the same as ``'Gaussian'``)
Lower-case strings are also allowed. The ``width`` parameter used
for the chosen smearing method is in eV units.
:charge:
Charge of the system in units of `|e|` (``charge=1`` means one
electron has been removed).
:nbands:
Each band can be occupied by two electrons.
ABC calculator example
======================
The constructor will look like this::
ABC(restart=None, ignore_bad_restart=False, label=None,**kwargs)
A calculator should be able to prefix all output files with a given
label or run the calculation in a directory with a specified name.
This is handled by the ``label`` argument. There are three
possibilities:
* Name of a file containing all results of a calculation (possibly
containing a directory).
* A prefix used for several files containing results. The label may
have both a directory part and a prefix part like ``'LDA/mol1'``.
* Name of a directory containing result files with fixed names.
Each calculator can decide what the default value is: ``None`` for no
output, ``'-'`` for standard output or something else.
If the ``restart`` argument is given, atomic configuration, input
parameters and results will be read from a previous calculation from
the file(s) pointed to by the ``restart`` argument. It is an error if
those files don't exist and are corrupted. This error can be ignored
bu using ``ignore_bad_restart=True``.
The ``atoms`` argument is discussed below. All additional parameters
are given as keyword arguments.
Example: Do a calculation with ABC calculator and write results to
:file:`si.abc`:
>>> atoms = ...
>>> atoms.calc = ABC(label='si.abc', xc='LDA', kpts=3.0)
>>> atoms.get_potential_energy()
-1.2
Read atoms with ABC calculator attaced from a previous calculation:
>>> atoms = ABC.read_atoms('si.abc')
>>> atoms.calc
<ABC-calculator>
>>> atoms.get_potential_energy()
-1.2
The ``ABC.read_atoms('si.abc')`` statement is equivalent to::
ABC(restart='si.abc', label='si.abc').get_atoms()
If we do:
>>> atoms = ABC.read_atoms('si.abc')
>>> atoms.rattle() # change positions and/or
>>> atoms.calc.set(xc='PBE') # change a calculator-parameter
>>> atoms.get_potential_energy()
-0.7
then the :file:`si.abc` will be overwritten or maybe appended to.
The command used to start the ABC code can be given in an environment
variable called ``ASE_ABC_COMMAND`` or as a ``command``
keyword. The command can look like this::
mpiexec abc PREFIX.input > PREFIX.output
or like this::
~/bin/start_abc.py PREFIX
The ``PREFIX`` strings will be substituted by the ``label`` keyword.
Implementation
==============
* Portability (Linux/Windows): ``os.system('Linux commands')`` not allowed.
* Common base class for all calculators: ``Calculator``. Takes care
of restart from file logic, handles setting of parameters and checks
for state changes.
* A ``FileIOCalculator`` for the case where we need to:
* write input file(s)
* run Fortran/C/C++ code
* read output file(s)
* Helper function to deal with ``kpts`` keyword.
Testing
=======
An interface must pass the tests located under :git:`ase/test/calculator/`.
|
