# 2.12. Calculate reference values with ParAMS¶

In all previous tutorials, the reference data was either already pre-calculated, or calculated by setting up a job in AMSinput and running it in the normal way before importing the results to ParAMS.

You can also use ParAMS to calculate the reference values. That is illustrated in this tutorial.

This can be useful if you, for example:

• want to reevaluate (parts of) the training set with a different reference method,
• have added a reaction energy without a reference value, or
• only have a few reference jobs that are relatively quick to calculate.

Note

It is usually better to first run the reference calculations and then import them into ParAMS (i.e., to not follow this tutorial, but instead the Import training data (GUI) or Import training data (Python) tutorials). That way you can:

• run the reference calculations on multiple nodes,
• store the reference calculations and results in arbitrary places on disk,
• inspect the reference results and correct any errors before the parametrization, and
• use the results importer for PESScans which generate plots.

## 2.12.2. The input files¶

### 2.12.2.1. Training set without reference values (training_set.yaml)¶

Open the ParAMS GUI: SCM → ParAMS
File → Open the job_collection.yaml file in the example directory
Switch to the Training Set panel
Note that the Values column is empty: There are no reference values!

The reference values will be calculated when you start the parametrization.

Unlike the training_set.yaml file in the previous tutorial, this example’s training_set.yaml does not contain any reference values:

---
dtype: DataSet
version: '2022.101'
---
Expression: energy('Ar32_frame001')-energy('Ar32_frame002')
Weight: 1.0
Sigma: 0.054422772491975996
Unit: eV, 27.211386245988
---
Expression: energy('Ar32_frame003')-energy('Ar32_frame002')
Weight: 1.0
Sigma: 0.054422772491975996
Unit: eV, 27.211386245988
---
Expression: forces('Ar32_frame001')
Weight: 1.0
Sigma: 0.15426620242897765
Unit: eV/angstrom, 51.422067476325886
---
Expression: forces('Ar32_frame002')
Weight: 1.0
Sigma: 0.15426620242897765
Unit: eV/angstrom, 51.422067476325886
---
Expression: forces('Ar32_frame003')
Weight: 1.0
Sigma: 0.15426620242897765
Unit: eV/angstrom, 51.422067476325886
...


This tutorial shows you how you can calculate the reference values (in units of Unit) with params.

### 2.12.2.2. Jobs and Engines (job_collection.yaml, job_collection_engines.yaml)¶

All Jobs that are mentioned in training set entries without a reference value, will be calculated before the parametrization starts with the help of a Reference Engine.

Switch to the Jobs panel
The Reference Engine column contains entries with dftb;;kspace;;quality;GammaOnly;model;GFN1-xTB;.

This rather cryptic ID is a reference engine id.

Switch to the Engines panel
Double-click in the Detail column where it says Engine dftb   kspace .......
You then see the Engine settings in the top box. If you are familiar with this type of input, you can directly edit it in the text box.
Below, you see the Engine ID. Change the ID to something more familiar, for example GFN1xTB_GammaPoint (do not use spaces in the name).
Click OK
This updates the Engine ID in the table

This affects all jobs with that particular reference engine.

To edit the engine used for a job:

Switch back to the Jobs panel
The column with reference engines have been updated to contain the id you chose
Double-click on the Ar32_frame002 job in the Detail column (where it says SinglePoint + gradients)
Click the AMSinput button next to Reference Engine
This brings up an AMSinput window on the panel (if you do not have a DFTB license, choose an engine for which you have a valid license).
The engine settings that will be used for the job are shown. For example, KSpace is set to GammaOnly.
You can change the DFTB settings. For example, set KSpace to Basic and Occupation to Fermi
Close the AMSinput window
In the dialog “Pass to ParAMS?” click Yes
A window informs that you that related reference values will be cleared. In this tutorial there are no reference values yet anyway. Click OK
This creates a new reference engine GFN1xTB;2526569033. The numbers are a hash of the settings.
The Ar32_frame002 job has the new reference engine. You can rename it on the Engines panel if you prefer.

In this way, you can create an arbitrary number of engines, or choose already-created engines.

Switch to the Jobs panel
Double-click on the Ar32_frame002 job in the Detail column (where it says SinglePoint + gradients)
In the Reference Engine drop-down, choose the original reference engine (GFN1xTB_GammaPoint).
Click OK
Verify that all jobs have the GFN1xTB_GammaPoint engine

Unlike the previous tutorial, here each entry in the job_collection.yaml has a ReferenceEngineID. For example, the first entry is

  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 --- Engines: job_collection_engines.yaml dtype: JobCollection version: '2022.101' --- ID: 'Ar32_frame001' ReferenceEngineID: dftb;;kspace;;quality;GammaOnly;model;GFN1-xTB; AMSInput: | properties gradients Yes End system Atoms Ar 5.1883477539 -0.4887475488 7.9660568076 Ar 5.7991822399 0.4024595652 2.5103286966 Ar 6.1338265157 5.5335946219 7.0874208384 Ar 4.6137188191 5.9644505949 3.0942810122 Ar 8.4186778390 7.6292969115 8.0729664423 Ar 8.3937816110 8.6402371806 2.6057806799 Ar 7.5320205143 1.7666481606 7.7525889818 Ar 8.5630139885 2.0472039529 2.6380554086 Ar 2.6892353632 7.8435284207 7.7883054306 Ar 2.4061636915 7.5716025415 2.4535180075 Ar 2.2485171283 2.9764130946 7.8589298904 Ar 3.0711058946 1.8500587164 2.5620921469 Ar 7.6655637500 -0.4865893003 0.0018797080 Ar 7.7550067215 -0.0222821825 4.8528637785 Ar 7.7157262425 4.6625079517 -0.3861722152 Ar 7.7434900996 5.2619590353 4.2602386226 Ar 3.4302237084 -0.2708640738 0.6280466620 Ar 2.8648051689 0.6106220610 6.1208342905 Ar 3.2529823775 5.7151788324 -0.2024448179 Ar 2.0046357208 4.9353027402 5.4968740217 Ar 0.9326855213 8.0600564695 -0.3181225099 Ar -0.5654205469 8.5703446434 5.8930973456 Ar -0.9561293133 2.1098403312 -0.0052667919 Ar -0.8081417664 3.2747992855 5.5295389610 Ar 5.5571960244 7.5645919074 0.1312355350 Ar 4.4530832384 7.6170633330 5.4810860433 Ar 5.1235367625 2.7983577675 -0.3161069611 Ar 5.2048439076 2.9885672135 4.5193274119 Ar -0.2535891591 0.0134355189 8.3061692970 Ar 0.5614183785 -0.1927751317 3.2355155467 Ar -0.0234943080 5.0313863031 8.0451075074 Ar -0.4760138873 6.2617510830 2.5759742219 End Lattice 10.5200000000 0.0000000000 0.0000000000 0.0000000000 10.5200000000 0.0000000000 0.0000000000 0.0000000000 10.5200000000 

The ReferenceEngineID refers to an engine in job_collection_engines.yaml, which is an Engine Collection. Each entry has a unique ID, and an AMSInput block containing calculation settings for the AMS engine.

---
Jobs: job_collection.yaml
dtype: EngineCollection
version: '2022.101'
---
ID: 'dftb;;kspace;;quality;GammaOnly;model;GFN1-xTB;'
AMSInput: |
Engine dftb
kspace
quality GammaOnly
End
model GFN1-xTB
EndEngine
...


In this example, there is only one reference engine. It has the ID dftb;;kspace;;quality;GammaOnly;model;GFN1-xTB;. The ID could be any string. It does not affect the results, but should describe the reference engine. Each job in the job collection with this ReferenceEngineID will be evaluated with this reference engine.

The AMSInput affects the calculation. In this example, it sets up a GFN1-xTB engine with Γ-point sampling. The AMSInput will be added verbatim to the input to the reference job.

Note

If you do not have DFTB license, change the Engine block in job_collection_engines.yaml to

Engine ForceField
Type UFF
EndEngine


to instead use a UFF force field as the reference method.

## 2.12.3. Calculate the reference values¶

File → Save As
Save with the name calc_ref_values.params
File → Run. This brings up AMSjobs
Before the parametrization starts, you can see for example “Job Ar32_frame001 RUNNING” in AMSjobs
Switch back to the ParAMS window
On the Training Set panel, the reference values have been added

To run the reference jobs and generate the reference data:

"$AMSBIN/params" genref  That only runs the reference calculations and adds the reference data to the training set. To run the parametrization, follow with "$AMSBIN/params" optimize


Alternatively, you can run both the genref and optimize commands together using run:

"\$AMSBIN/params" run


## 2.12.4. Output files for reference calculations and data¶

In the calc_ref_values.results folder (or the current directory if you use scripting), you will find

### 2.12.4.1. The reference.cache folder¶

For example, the file reference.cache/Ar32_frame001/Ar32_frame001.in contains the input to the Ar32_frame001 job, which combines input from the job collection and engine collection:

properties
End

system
Atoms
Ar       5.1883477539      -0.4887475488       7.9660568076
Ar       5.7991822399       0.4024595652       2.5103286966
Ar       6.1338265157       5.5335946219       7.0874208384
Ar       4.6137188191       5.9644505949       3.0942810122
Ar       8.4186778390       7.6292969115       8.0729664423
Ar       8.3937816110       8.6402371806       2.6057806799
Ar       7.5320205143       1.7666481606       7.7525889818
Ar       8.5630139885       2.0472039529       2.6380554086
Ar       2.6892353632       7.8435284207       7.7883054306
Ar       2.4061636915       7.5716025415       2.4535180075
Ar       2.2485171283       2.9764130946       7.8589298904
Ar       3.0711058946       1.8500587164       2.5620921469
Ar       7.6655637500      -0.4865893003       0.0018797080
Ar       7.7550067215      -0.0222821825       4.8528637785
Ar       7.7157262425       4.6625079517      -0.3861722152
Ar       7.7434900996       5.2619590353       4.2602386226
Ar       3.4302237084      -0.2708640738       0.6280466620
Ar       2.8648051689       0.6106220610       6.1208342905
Ar       3.2529823775       5.7151788324      -0.2024448179
Ar       2.0046357208       4.9353027402       5.4968740217
Ar       0.9326855213       8.0600564695      -0.3181225099
Ar      -0.5654205469       8.5703446434       5.8930973456
Ar      -0.9561293133       2.1098403312      -0.0052667919
Ar      -0.8081417664       3.2747992855       5.5295389610
Ar       5.5571960244       7.5645919074       0.1312355350
Ar       4.4530832384       7.6170633330       5.4810860433
Ar       5.1235367625       2.7983577675      -0.3161069611
Ar       5.2048439076       2.9885672135       4.5193274119
Ar      -0.2535891591       0.0134355189       8.3061692970
Ar       0.5614183785      -0.1927751317       3.2355155467
Ar      -0.0234943080       5.0313863031       8.0451075074
Ar      -0.4760138873       6.2617510830       2.5759742219
End
Lattice
10.5200000000     0.0000000000     0.0000000000
0.0000000000    10.5200000000     0.0000000000
0.0000000000     0.0000000000    10.5200000000
End
End

Engine dftb
kspace
quality GammaOnly
End
model GFN1-xTB
EndEngine



The normal AMS output can be found in the same folder: the logfile, standard outputfile, and the binary ams.rkf and dftb.rkf files.

### 2.12.4.2. The training_set.ref.yaml file¶

The training_set.ref.yaml file contains the calculated reference values. For example, it starts with

---
dtype: DataSet
version: '2022.101'
---
Expression: energy('Ar32_frame001')-energy('Ar32_frame002')
Weight: 1.0
Sigma: 0.054422772491975996
ReferenceValue: 0.20395942701637979
Unit: eV, 27.211386245988
---
Expression: energy('Ar32_frame003')-energy('Ar32_frame002')
Weight: 1.0
Sigma: 0.054422772491975996
ReferenceValue: 0.22060005303998803
Unit: eV, 27.211386245988
---
Expression: forces('Ar32_frame001')
Weight: 1.0
Sigma: 0.15426620242897765
ReferenceValue: |


These were the reference values that were used in the Getting Started: Lennard-Jones Potential for Argon tutorial.