Domain calculations
If multiple structures coexist on the sample, then the experimental beams are an incoherent superposition of the beam sets diffracted from each of the different structural domains. This means that the different structures must be optimized at the same time to optimize the \(R\) factor between calculated and experimental I(V) curves. This page covers how the structure of the input files for ViPErLEED changes when domains are present.
Tip
While domain calculations can be run from scratch (i.e., including the
reference calculations) from multiple sets of input files,
a way to get more user control is to first execute reference calculations
separately for the different structures, then start the domain calculation
from the Tensors_<index>.zip files produced
by those reference calculations. This way, one can verify the correct
execution of the Initialization for each domain, that the detected
symmetries are sensible, that the theoretical beam sets for the different
domains are as expected, etc., before launching into the simultaneous
optimization of the structures.
Note
TensErLEED requires the different structures to be calculated on the same surface supercell, i.e. with the same unit cell in the POSCAR file, and the same SUPERLATTICE parameter for each domain. Since changing the unit-cell size may change the detected symmetry, the SYMMETRY_CELL_TRANSFORM parameter allows defining a base unit cell and linking redundant atoms by translational symmetry.
In addition to the surface unit cell and the SUPERLATTICE parameter, the following settings must also be the same in each of the reference calculations (it is recommended to fix the PARAMETERS explicitly):
Running the domain calculations
To execute a domain calculation, set up a base folder (my_domain_calc
in Listing 27) containing all the normal input files,
except for the ones specifically concerned with the structures,
i.e., without POSCAR and VIBROCC. Likewise, the
PARAMETERS file should contain no parameters concerned with
interpretation of POSCAR or VIBROCC, such as, e.g., BULK_REPEAT,
ELEMENT_MIX, SITE_DEF, etc.; if any such parameter is present,
viperleed.calc will raise an error.
Finally, in the PARAMETERS file, do define the DOMAIN
parameter once for each of the domains that should be included. The
DOMAIN parameter can point to an absolute or relative path from
which the input data for a given domain should be fetched. The path may
point to a complete Tensors_<index>.zip file
(e.g., my_domain_2/Tensors/Tensors_005.zip in
Listing 27) or to a folder containing the
usual input files for a reference calculation
(EXPBEAMS and DISPLACEMENTS files in the subfolder are ignored),
as those in my_domain_1 of Listing 27. If
the target path is a directory in which previous ViPErLEED calculations
have been executed, viperleed.calc will check whether there is a Tensors
folder, and fetch the highest-number Tensors_<index>.zip file.
For more information, see the DOMAIN page. Use the DOMAIN_STEP
parameter to define the step width for domain-area variations.
my_domain_calc/
├── my_domain_1/ <-- Use input files, requires reference calculation
│ ├── PARAMETERS
│ ├── POSCAR
│ ├── VIBROCC
│ └── DISPLACEMENTS <-- Not used
├── my_domain_2/ <-- Use most recent Tensors
│ ├── Tensors/
│ │ ├── ...
│ │ └── Tensors_005.zip
│ ├── PARAMETERS <-- Use Tensors_005 instead of this
│ ├── POSCAR <-- Use Tensors_005 instead of this
│ └── VIBROCC <-- Use Tensors_005 instead of this
├── EXPBEAMS.csv
├── DISPLACEMENTS
└── PARAMETERS
You can then run viperleed.calc as usual.
Listing 28 shows the tree structure at the end of the
domain calculation. All structure-specific output files (e.g., POSCAR,
VIBROCC) are collected in the respective domain subfolders (i.e.,
my_domain_1 and my_domain_2). Instead, output concerning all
domains taken together will go to the main my_domain_calc folder (e.g.,
the Search-progress.pdf file and the \(R\)-factor plots
after the Superposition calculation).
my_domain_calc/
├── history/ <-- Created by bookkeeper, for the main directory
│ └── t000.r001_<timestamp>/
│ └── ...
├── my_domain_1/ <-- Use input files, requires reference calculation
│ ├── history/ <-- Created by bookkeeper, for my_domain_1
│ │ ├── ...
│ │ └── t001.r001_<timestamp>/
│ │ └── ...
│ ├── OUT/ <-- Created by calc at end
│ │ ├── POSCAR
│ │ ├── VIBROCC
│ │ └── ...
│ ├── SUPP/ <-- Created by calc at end
│ │ ├── POSCAR_bulk
│ │ └── ...
│ ├── Tensors/ <-- Created by calc at end
│ │ └── Tensors_001.zip
│ ├── history.info <-- Created by bookkeeper, for my_domain_1
│ ├── PARAMETERS
│ ├── PARAMETERS_ori
│ ├── POSCAR
│ ├── POSCAR_ori
│ ├── VIBROCC
│ ├── VIBROCC_ori
│ └── DISPLACEMENTS <-- Not used
│
├── my_domain_2/ <-- Use most recent Tensors
│ ├── history/ <-- Created by bookkeeper, for my_domain_2
│ │ ├── ...
│ │ └── t005.r001_<timestamp>/
│ │ └── ...
│ ├── OUT/ <-- Created by calc at end
│ │ ├── POSCAR
│ │ ├── VIBROCC
│ │ └── ...
│ ├── SUPP/ <-- Created by calc at end
│ │ ├── POSCAR_bulk
│ │ └── ...
│ ├── Tensors/
│ │ ├── ...
│ │ └── Tensors_005.zip
│ ├── history.info <-- Created by bookkeeper, for my_domain_2
│ ├── PARAMETERS
│ ├── PARAMETERS_ori <-- The unused one
│ ├── POSCAR
│ ├── POSCAR_ori <-- The unused one
│ ├── VIBROCC
│ └── VIBROCC_ori <-- The unused one
│
├── OUT/
│ ├── Rfactor_analysis_superpos.pdf
│ ├── Search_progress.pdf
│ └── ...
├── DISPLACEMENTS
├── EXPBEAMS.csv
├── history.info <-- Created by bookkeeper, for the main directory
├── PARAMETERS_ori
├── PARAMETERS
└── viperleed-calc-<timestamp>.log
To specify which segments should be run, either use the RUN parameter
as usual, or set RUN = 4 1 as a shorthand for a domain calculation, plus
a final reference calculation for the result of the optimization. This will be
interpreted as RUN = 2-3 1 or RUN = 1-3 1, depending on whether the
input files are compatible Tensors.zip files or whether a reference
calculation is needed, respectively. For RUN = 4, initial reference
calculations will only be executed for the domains that need them. Specify
RUN = 1-3 explicitly to rerun reference calculations for all domains.
However, as discussed above, it is recommended to run the reference
calculations separately beforehand for better control.
Warning
It is important to execute an explicit reference calculation at the end
of a multi-domain optimization, especially if additional multi-domain
optimizations are planned. In fact, subsequent steps will always start
from the most recent Tensors of each domain, i.e., the structure
at the most recent reference calculation.
See also Issue #337.
bookkeeper will automatically run both in the root directory (i.e.,
my_domain_calc) as well as in all the domain subfolders (i.e.,
my_domain_1 and my_domain_2), producing for each the usual
history folder and history.info file.[1]
As for a single-domain calculation, it will also copy the appropriate
OUT files and rename the corresponding inputs with an _ori
suffix, as displayed in Listing 28. This ensures that each
following execution of viperleed.calc will use the results from the previous one as
inputs (as long as each run ends with a reference calculation, see
Issue #337).
See the Bookkeeper page for more details.
Warning
Notice that, for folder my_domain_2, the files that are given an
_ori suffix are those that were already present in the root folder
before viperleed.calc started. These are not the exact files that were taken as
inputs: the latter were fetched from Tensors/Tensors_005.zip.
These files are normally the same, as long as a reference calculation
was executed in my_domain_2 as the last step before starting
the multi-domain calculation.
See also Issue #337.
Changed in version 0.13.0: In earlier versions of viperleed.calc, the results of the calculations from each
domain in a domain calculation would not be copied back from the work
folder. They were thus also not processed by bookkeeper.
The DISPLACEMENTS file for domains
Instead of specifying DISPLACEMENTS in each of the input subfolders,
DISPLACEMENTS are defined in the main folder for all domains.
The syntax is similar to the way consecutive searches are specified, with an
extra header line specifying which domain is being addressed, e.g., for a
calculation with two domains called 1x1 and 2x1:
== SEARCH z
== DOMAIN 1x1
= GEO_DELTA
* L(1) z = -0.1 0.1 0.02
* L(2) z = -0.05 0.05 0.025
== DOMAIN 2x1
= GEO_DELTA
* L(1-2) z = -0.1 0.1 0.02
* L(3) z = -0.05 0.05 0.025
Note
Indentation is allowed, but does not affect the functionality.
Fetching domain inputs from other filesystem locations
The DOMAIN parameter also supports the specification of other locations
from which inputs for each domain should be collected.
Listing 29 shows an example of such a filesystem: inputs
for the domains defined in my_domain_calc/PARAMETERS are to be fetched
from the domain_1_somewhere_else and domain_2_somewhere_else
folders. This section describes the differences that such a layout entails, as
compared to the simpler one in Listing 27.
my_domain_calc/
├── EXPBEAMS.csv
├── DISPLACEMENTS
└── PARAMETERS
domain_1_somewhere_else/
├── PARAMETERS
├── POSCAR
├── VIBROCC
└── DISPLACEMENTS <-- Not used
domain_2_somewhere_else/
└── Tensors/
├── ...
└── Tensors_005.zip
In this case, viperleed.calc will create new subfolders of my_domain_calc,
uniquely named from either the user-given name or a progressive index, as
Domain_<name-or-index>. Only the necessary input files for each domain
are copied there from the source directories.
Listing 30 shows the structure of the
my_domain_calc folder after execution. Notice that file
DISPLACEMENTS was not copied from domain_1_somewhere_else,
and only the most recent tensor file (Tensors_005.zip) was
collected from domain_2_somewhere_else.
my_domain_calc/
├── Domain_1/ <-- Created by calc at initialization
│ ├── history/ <-- Created by bookkeeper, for Domain_1
│ │ └── t001.r001_<timestamp>/
│ │ └── ...
│ ├── OUT/ <-- Created by calc at end
│ │ ├── POSCAR
│ │ ├── VIBROCC
│ │ └── ...
│ ├── SUPP/ <-- Created by calc at end
│ │ ├── POSCAR_bulk
│ │ └── ...
│ ├── Tensors/ <-- Created by calc at end
│ │ └── Tensors_001.zip
│ ├── history.info <-- Created by bookkeeper, for Domain_1
│ ├── PARAMETERS
│ ├── PARAMETERS_ori <-- Copied by calc from /domain_1_somewhere_else/
│ ├── POSCAR
│ ├── POSCAR_ori <-- Copied by calc from /domain_1_somewhere_else/
│ ├── VIBROCC
│ └── VIBROCC_ori <-- Copied by calc from /domain_1_somewhere_else/
│
├── Domain_another/ <-- Created by calc at initialization
│ ├── history/ <-- Created by bookkeeper, for Domain_another
│ │ └── t005.r001_<timestamp>/
│ │ └── ...
│ ├── OUT/ <-- Created by calc at end
│ │ ├── POSCAR
│ │ ├── VIBROCC
│ │ └── ...
│ ├── SUPP/ <-- Created by calc at end
│ │ ├── POSCAR_bulk
│ │ └── ...
│ ├── Tensors/ <-- Copied by calc from /domain_2_somewhere_else/
│ │ └── Tensors_005.zip
│ ├── history.info <-- Created by bookkeeper, for Domain_another
│ ├── PARAMETERS
│ ├── POSCAR
│ └── VIBROCC
│
├── history/ <-- Created by bookkeeper, for the main directory
│ └── t000.r001_<timestamp>/
│ └── ...
├── OUT/
│ ├── Rfactor_analysis_superpos.pdf
│ ├── Search_progress.pdf
│ └── ...
├── viperleed-calc-<timestamp>.log
├── EXPBEAMS.csv
├── DISPLACEMENTS
├── history.info <-- Created by bookkeeper, for the main directory
└── PARAMETERS
Execution then proceeds as described in Running the domain calculations, treating
my_domain_calc as an independent folder. No further reference
is made to the original paths where the inputs were collected from.
In particular, all structure-specific output files will go to the
newly created subfolders, not to the original paths.
Additionally, the DOMAIN parameters in the PARAMETERS file of
the main directory (i.e., my_domain_calc/PARAMETERS, as well
as my_domain_calc/OUT/PARAMETERS) are automatically modified
to point to the newly created subfolders of my_domain_calc
(i.e., Domain_1 and Domain_another in
Listing 30).
Changed in version 0.13.0: The main PARAMETERS file is updated such that each DOMAIN points
to the subfolders of the directory in which viperleed.calc was executed.