1.. _doc.calculators:
2
3===========
4Calculators
5===========
6
7A calculator is the central agent that exchanges information between a model and
8the minimizer.
9
10- It uses the computation methods provided by a model to calculate the energy,
11  forces, etc. and pass these properties, together with the corresponding
12  reference data, to :class:`~kliff.loss.Loss` to construct a loss function to be
13  minimized by the optimizer.
14- It also inquires the model to get parameters that are going to be optimized, and
15  provide these parameters to the optimizer, which will be used as the initial values
16  by the optimizer to carry out the optimization.
17- In the reverse direction, at each optimization step, the calculator grabs the new
18  parameters from the optimizer and update the model parameters with the new ones.
19  So, in the next minimization step, the loss function will be calculated using the
20  new parameters.
21
22
23A calculator for the physics-motivated potential can be created by:
24
25.. code-block:: python
26
27    from kliff.calculators import Calculator
28
29    model = ...  # create a model
30    configs = ...  # get a list of configurations
31    calc = Calculator(model)
32    calc.create(configs, use_energy=True, use_forces=True, use_stress=False)
33
34It creates a calculator for a ``model`` (discussed in :ref:`doc.models`), and
35``configs`` is a list of :class:`~kliff.dataset.Configuration` (discussed in
36:ref:`doc.dataset`), for which the calculator is going to make predictions.
37``use_energy``, ``use_forces``, and ``use_stress`` inform the calculator whether
38`energy`, `forces`, and `stress` will be requested from the calculator.
39If the potential is to be trained on `energy` only, it would be better to set
40``use_forces`` and ``use_stress`` to ``False``, which turns off the calculations for
41``forces`` and ``stress`` and thus can speed up the fitting process.
42
43
44Other methods of the calculator include:
45
46- `Initialization`:
47  :meth:`~kliff.calculators.Calculator.get_compute_arguments`.
48- `Property calculation using a model`:
49  :meth:`~kliff.calculators.Calculator.compute`,
50  :meth:`~kliff.calculators.Calculator.get_compute_arguments`,
51  :meth:`~kliff.calculators.Calculator.compute`,
52  :meth:`~kliff.calculators.Calculator.get_energy`,
53  :meth:`~kliff.calculators.Calculator.get_forces`,
54  :meth:`~kliff.calculators.Calculator.get_stress`,
55  :meth:`~kliff.calculators.Calculator.get_prediction`,
56  :meth:`~kliff.calculators.Calculator.get_reference`.
57- `Optimizing parameters`:
58  :meth:`~kliff.calculators.Calculator.get_opt_params`,
59  :meth:`~kliff.calculators.Calculator.get_opt_params_bounds`,
60  :meth:`~kliff.calculators.Calculator.update_model_params`.
61
62.. seealso::
63    See :class:`kliff.calculators.Calculator` for a complete list of the member
64    functions and
65    their docs.
66