ViPErLEED

https://www.viperleed.org/stable
Admin
ViPErLEED is an open-source project providing tools for quantitative low-energy electron diffraction...
Tokens:375,625
Snippets:4,010
Trust Score:5.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic OPTIMIZE Syntax Examples

Source: https://www.viperleed.org/stable/_sources/content/calc/parameters/optimize.rst.txt

Demonstrates the basic syntax for the OPTIMIZE parameter, showing how to specify the parameter to optimize and its initial step value. This is the minimum form required to start an optimization.

```fortran
OPTIMIZE V0i = 0.5                                ! optimize the imaginary part of the inner potential, with an initial step of 0.5 eV.
```

```fortran
OPTIMIZE V0i = step 0.5                           ! same as above
```

```fortran
OPTIMIZE V0i = step -0.5                          ! same as above, but take the initial step towards smaller V0i rather than larger
```

--------------------------------

### Install Coverage and Run Tests

Source: https://www.viperleed.org/stable/_sources/content/appendix/notes_for_developers.rst.txt

Install the coverage tool and then run tests while generating a coverage report. This is useful for assessing test completeness.

```bash
python -m pip install coverage
```

```bash
python -m coverage run -m pytest .
```

```bash
python -m coverage html
```

--------------------------------

### Install coverage and run tests

Source: https://www.viperleed.org/stable/content/appendix/notes_for_developers.html

Installs the coverage tool and then runs tests while generating an HTML coverage report. This is useful for assessing test coverage.

```bash
python -m pip install coverage
python -m coverage run -m pytest .
python -m coverage html

```

--------------------------------

### Install All Development Dependencies

Source: https://www.viperleed.org/stable/_sources/content/appendix/notes_for_developers.rst.txt

Install all necessary dependencies for developing ViPErLEED. This includes packages beyond those needed for distribution.

```bash
python -m pip install --upgrade -r requirements/dev.txt
```

--------------------------------

### ViPErLEED PARAMETERS File Example

Source: https://www.viperleed.org/stable/_sources/content/calc/example_systems/Ni%28110%29.ipynb.txt

This is an example of the PARAMETERS file used by ViPErLEED. It configures global settings, structure interpretation, and VIBROCC parameters for surface calculations.

```console
RUN = 1
THEO_ENERGIES = -15 15
LMAX = 4
HALTING = 3
BULK_LIKE_BELOW = 0.42
# SITE_DEF = 
T_DEBYE = 350
T_EXPERIMENT = 300
VIBR_AMP_SCALE = 0.1
```

--------------------------------

### Install MinGW Toolchain

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Install the MinGW-w64 toolchain, which includes essential development tools for Windows.

```bash
pacman -S mingw-w64-x86_64-toolchain
```

--------------------------------

### Example Directory Tree for Domain Calculation Inputs

Source: https://www.viperleed.org/stable/_sources/content/calc/sections/domain_calculation.rst.txt

This example shows the directory structure for setting up input files for a domain calculation. It illustrates how to organize input files for different domains, either by providing reference calculation files or pre-computed tensor files.

```console
my_domain_calc/
├── my_domain_1/       <-- Use input files, requires reference calculation
│   ├── PARAMETERS
│   ├── POSCAR
│   ├── VIBROCC
│   ├── IVBEAMS        <-- Not used
│   └── 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

```

--------------------------------

### Install Development Tools

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Install base development packages, CMake, and Git using MSys2's pacman package manager.

```bash
pacman -S base-devel
pacman -S mingw-w64-x86_64-cmake
pacman -S git
```

--------------------------------

### Process Random Start Configuration

Source: https://www.viperleed.org/stable/_modules/viperleed/calc/files/iosearch.html

Handles the 'crandom' search start configuration by generating a population of configurations, starting with a centered configuration and then adding random configurations.

```python
else:    # rp.SEARCH_START == "crandom"
            pop = [rp.getCenteredConfig()]
            for i in range(1, rp.SEARCH_POPULATION):
                pop.append(rp.getRandomConfig())
            for p in pop:
                ol = ""
                for v in p:
                    ol += formatter['ctrl'].write([v])
                output += ol + "\n"
```

--------------------------------

### ViPErLEED IVBEAMS File Example

Source: https://www.viperleed.org/stable/_sources/content/calc/example_systems/Ni%28110%29.ipynb.txt

This is an example of the IVBEAMS file for ViPErLEED. It specifies the diffraction beams for which output spectra should be generated, useful for theory-theory comparisons.

```console
0 0
0 1
1 0
1 1
```

--------------------------------

### Test LAPACK Installation

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Download a C++ test program, compile it using g++, link against the LAPACK library, and then run the executable to verify the LAPACK installation.

```bash
cd ~
wget http://www.math.ucla.edu/~wotaoyin/software/lapack_test.cpp  # download
g++ lapack_test.cpp -llapack -o lapack_test     # build
./lapack_test                                   # run
```

--------------------------------

### Install Distribution Dependencies

Source: https://www.viperleed.org/stable/_sources/content/appendix/notes_for_developers.rst.txt

Install the dependencies required for building ViPErLEED for distribution. Run this command from your local repository clone.

```bash
python -m pip install --upgrade -r requirements/dist.txt
```

--------------------------------

### Example of explicit FORTRAN_COMP and post flags

Source: https://www.viperleed.org/stable/content/calc/parameters/fortran_comp.html

An example demonstrating how to explicitly set the FORTRAN_COMP, post flags, and MPI compiler for a Fortran build.

```fortran
FORTRAN_COMP = 'ifort -O3 -I/opt/intel/mkl/include'
FORTRAN_COMP post = '-L/opt/intel/mkl/lib/intel64 -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core -liomp5 -lpthread -lm -ldl'
FORTRAN_COMP mpi = 'mpiifort -O2'
```

--------------------------------

### Handle control.chem file for starting configuration

Source: https://www.viperleed.org/stable/_modules/viperleed/calc/files/iosearch.html

Determines the path to the 'control.chem' file, logging warnings if it's not found in the working directory and using a default path if necessary. Sets search start mode and halting level based on file availability.

```python
if rp.SEARCH_START == "control":
        controlpath = ""
        if os.path.isfile("control.chem"):
            controlpath = "control.chem"
        elif os.path.isfile(os.path.join(DEFAULT_SUPP, "control.chem")):
            controlpath = os.path.join(DEFAULT_SUPP, "control.chem")
            logger.warning("No control.chem file found in working folder, "
                           f"using {DEFAULT_SUPP}/control.chem")
            rp.setHaltingLevel(1)
        else:
            logger.warning("No control.chem file found. Defaulting to random "
                           "starting configuration.")
            rp.SEARCH_START = "random"
            rp.setHaltingLevel(2)
```

--------------------------------

### Format Search Start Configuration Output

Source: https://www.viperleed.org/stable/_modules/viperleed/calc/files/iosearch.html

Formats and appends the search start configuration to the output string, indicating whether a certain start position or a random configuration is used.

```python
if rp.SEARCH_START == "random":
        output += (formatter['int'].write([0]).ljust(16) + "Certain start position (1) or random configuration (0)\n")
    else:
        output += (formatter['int'].write([1]).ljust(16) + "Certain start position (1) or random configuration (0)\n")
```

--------------------------------

### PHASESHIFTS File Example

Source: https://www.viperleed.org/stable/content/calc/files/input/phaseshifts.html

This example demonstrates the structure of a PHASESHIFTS file, showing the header with block count and potential parameters, followed by energy-dependent phase shifts for different sites and elements, broken down by angular momentum quantum number.

```text
3   -11.89   -0.15  -88.82   17.74      Ir(100)-O_example 221130-104323
0.5512
1.4793-1.0892 0.0178 0.0006 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.7672-0.3853-0.9502 0.0147 0.0007 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.7517-0.3790-0.9060 0.0152 0.0007 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.6615
1.3761-1.0791 0.0266 0.0010 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.8554-0.4496-0.8502 0.0263 0.0014 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.8396-0.4421-0.8243 0.0271 0.0014 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.7717
1.2832-1.0943 0.0360 0.0015 0.0001 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.9590-0.5219-0.8529 0.0406 0.0024 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.9430-0.5132-0.8329 0.0421 0.0025 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.8820
...

```

--------------------------------

### Install Intel oneAPI Base and HPC Toolkits

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Installs the Intel oneAPI Base Toolkit and HPC Toolkit. Replace <version> with the desired version number (e.g., 2024.2).

```bash
sudo apt install intel-basekit-<version> -y
sudo apt install intel-hpckit-<version> -y
```

--------------------------------

### Process Centered Start Configuration

Source: https://www.viperleed.org/stable/_modules/viperleed/calc/files/iosearch.html

Handles the 'centered' search start configuration by generating a population of configurations where each parameter is set to the midpoint of its range.

```python
elif rp.SEARCH_START == "centered":
            for i in range(0, rp.SEARCH_POPULATION):
                ol = ""
                for n in nsteps:
                    ol += formatter['ctrl'].write([(n+1)/2])
                output += ol + "\n"
```

--------------------------------

### Example: Fixed Fe-Ni Concentration

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/displacements/occdelta.rst.txt

This example demonstrates fixing the occupation of M_top sites to a specific ratio of 60% iron and 40% nickel.

```text
M_top = Fe 0.6, Ni 0.4              ! Occupation of M_top sites (M is a POSCAR element) will be fixed to 60% iron + 40% nickel.
```

--------------------------------

### Install ViPErLEED with GUI Dependencies

Source: https://www.viperleed.org/stable/_sources/content/installation.rst.txt

Install ViPErLEED along with the dependencies required for the graphical user interface. This enables data measurement and pattern simulation.

```console
python -m pip install viperleed[GUI]
```

--------------------------------

### Install all development dependencies

Source: https://www.viperleed.org/stable/content/appendix/notes_for_developers.html

Installs all dependencies required for ViPErLEED development, including those for distribution and testing. Execute this in your local ViPErLEED GitHub repository.

```bash
python -m pip install --upgrade -r requirements/dev.txt

```

--------------------------------

### Start WSL

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Initiates a Windows Subsystem for Linux session from the Windows terminal.

```bash
wsl
```

--------------------------------

### Ni(110) Surface System Setup

Source: https://www.viperleed.org/stable/_sources/content/calc/example_systems/Ni%28110%29.ipynb.txt

Defines the Ni(110) surface system with specific lattice parameters and atomic structure. This is a foundational setup for surface calculations.

```python
from ase.build import fcc110
from gpaw import GPAW, PW, Fermi

system = fcc110('Ni', size=(2, 2, 3), vacuum=10.0)
system.center(vacuum=10.0, axis=2)

calc = GPAW(mode=PW(500), \n              kpts=(2, 2, 1), \n              txt='ni110.txt', \n              occupations=Fermi(0.01), \n              h=0.2, \n              setups={'Ni': 'paw/PBE/Ni-q19.00.atompaw'} \n              )
system.set_calculator(calc)
```

--------------------------------

### ViPErLEED Log Output Example

Source: https://www.viperleed.org/stable/_sources/content/calc/example_systems/Ag%28100%29.rst.txt

This is an example of the expected output lines in the log file after a successful ViPErLEED calculation, showing detected symmetry and bulk repeat vectors.

```console
... 
Found unit cell type: square
Starting symmetry search...
Found plane group: p4m
Detected bulk repeat vector: [-1.44000 -1.44000 2.03647]
Checking bulk unit cell...
Found SUPERLATTICE = (1x1)
...
```

--------------------------------

### Example PHASESHIFTS File Content

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/phaseshifts.rst.txt

This example demonstrates the structure of a PHASESHIFTS file, including the header line with parameters and energy blocks containing phase shifts for different sites, elements, and angular momenta. Note that phase shifts for a single element can span multiple lines.

```text
3   -11.89   -0.15  -88.82   17.74      Ir(100)-O_example 221130-104323
0.5512
1.4793-1.0892 0.0178 0.0006 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.7672-0.3853-0.9502 0.0147 0.0007 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.7517-0.3790-0.9060 0.0152 0.0007 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.6615
1.3761-1.0791 0.0266 0.0010 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.8554-0.4496-0.8502 0.0263 0.0014 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.8396-0.4421-0.8243 0.0271 0.0014 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.7717
1.2832-1.0943 0.0360 0.0015 0.0001 0.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.9590-0.5219-0.8529 0.0406 0.0024 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
-0.9430-0.5132-0.8329 0.0421 0.0025 0.0001 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
0.8820
...
```

--------------------------------

### Process Control Start Configuration with Culling

Source: https://www.viperleed.org/stable/_modules/viperleed/calc/files/iosearch.html

Handles the 'control' search start configuration, including culling individuals based on SEARCH_CULL parameters. It prepares readable lines and determines the number of individuals to survive.

```python
if rp.SEARCH_START == "control":
            if cull and rp.SEARCH_CULL:
                try:
                    ncull = rp.SEARCH_CULL.nr_individuals(rp.SEARCH_POPULATION)
                except ValueError:  # Too small population
                    ncull = 0
                    logger.warning(
                        "SEARCH_CULL parameter too large: would cull "
                        "entire population. Culling will be skipped."
                        )
                if any([sp.parabolaFit["min"] is not None
                        for sp in rp.searchpars]):
                    # replace one by predicted best
                    getPredicted = True
                else:
                    getPredicted = False
                nsurvive = rp.SEARCH_POPULATION - ncull
                clines = controllines[2:]
                csurvive = []
                if rp.SEARCH_CULL.type_.is_genetic or getPredicted:
                    # prepare readable clines
                    try:
                        csurvive = [read_int_line(s, width=ctrl_width)
                                    for s in clines[:nsurvive]]
                    except ValueError:
                        if rp.SEARCH_CULL.type_.is_genetic:
                            logger.warning(
                                "SEARCH_CULL: Failed to read old "
                                "configuration from control.chem, cannot run "
                                "genetic algorithm. Defaulting to cloning."
                                )
                            rp.setHaltingLevel(1)
                            csurvive = []
                for (i, line) in enumerate(clines):
                    if i < nsurvive:
                        output += line
                    elif (rp.SEARCH_CULL.type_.is_random or
                          (rp.SEARCH_CULL.type_.is_genetic and csurvive)
                          or getPredicted):
                        if getPredicted:
                            bc = None
                            if csurvive:
                                bc = csurvive[0]
                            nc = rp.getPredictConfig(
                                best_config=bc,
                                mincurv=rp.PARABOLA_FIT["mincurv"])
                            getPredicted = False
                        elif rp.SEARCH_CULL.type_.is_random:
                            nc = rp.getRandomConfig()
                        else:  # "genetic"
                            nc = rp.getOffspringConfig(csurvive)
                        ol = ""
                        for v in nc:
                            ol += formatter['ctrl'].write([v])
                        output += ol + "\n"
                    else:    # "cloning"
                        output += clines[random.randrange(0, nsurvive)]
            else:  # don't cull
                for (i, line) in enumerate(controllines):
                    if i > 1:  # first 2 lines are empty
                        output += line
```

--------------------------------

### KPOINTS for Ni(110) Surface

Source: https://www.viperleed.org/stable/_sources/content/calc/example_systems/Ni%28110%29.ipynb.txt

Example KPOINTS file for a Ni(110) surface calculation. This setup uses a Monkhorst-Pack grid for sampling the Brillouin zone.

```text
Ni(110) surface
0
Gamma
4 4 1
0 0 0
```

--------------------------------

### Example PARAMETERS File Structure

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/parameters.rst.txt

Illustrates the basic structure of a PARAMETERS file, including parameter definitions, comments, and element-specific site definitions.

```none
LAYER_CUTS = 0.09 0.19 0.29 0.39 0.49
N_BULK_LAYERS = 2

! a comment

SITE_DEF Fe = siteA 38 41, siteB 50-55, topSite top(2)   !another comment
SITE_DEF O = topSite top(2)
```

--------------------------------

### Install Xcode Command-Line Tools

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

If you encounter errors during gfortran installation on macOS, ensure Xcode command-line tools are installed by running this command.

```bash
xcode-select --install
```

--------------------------------

### Install ViPErLEED Python Package

Source: https://www.viperleed.org/stable/_sources/content/installation.rst.txt

Use this command to install the latest version of ViPErLEED and its core dependencies from PyPI. This also installs command-line tools.

```console
python -m pip install viperleed
```

--------------------------------

### Install gfortran and dependencies on Debian-based Linux

Source: https://www.viperleed.org/stable/content/calc/install_tensor_leed.html

Installs the gfortran compiler, BLAS, and LAPACK libraries using apt. Ensure your package list is updated before installation.

```bash
sudo apt update
sudo apt install gfortran -y
```

```bash
gfortran --version
```

```bash
sudo apt install libblas-dev liblapack-dev
```

```bash
sudo apt install openmpi-bin
```

```bash
sudo apt install libopenmpi-dev
```

--------------------------------

### Install Cairo Dependencies on macOS

Source: https://www.viperleed.org/stable/_sources/content/installation.rst.txt

On macOS, install pkg-config and cairo using Homebrew if the 'mplcairo' package installation fails due to missing cairo dependencies.

```bash
brew install pkg-config cairo
```

--------------------------------

### Start WSL

Source: https://www.viperleed.org/stable/content/calc/install_tensor_leed.html

Initiate a Windows Subsystem for Linux session by typing `wsl` in your terminal.

```bash
wsl

```

--------------------------------

### Install Cairo Dependencies on Linux/WSL

Source: https://www.viperleed.org/stable/_sources/content/installation.rst.txt

On Linux or Windows Subsystem for Linux, install pkg-config and libcairo2-dev if the 'mplcairo' package installation fails due to missing cairo dependencies.

```bash
sudo apt install pkg-config libcairo2-dev
```

--------------------------------

### Default V0_REAL Syntax Example

Source: https://www.viperleed.org/stable/_sources/content/calc/parameters/v0_real.rst.txt

Illustrates the default syntax for V0_REAL, which uses the Rundgren form and constants from the PHASESHIFTS file.

```none
V0_REAL = -1*max(-10.17, -0.08 - 74.19/sqrt(EE+19.18))
V0_REAL = RUNDGREN -10.17 -0.08 -74.19 19.18
```

--------------------------------

### Install gfortran and Open MPI on macOS

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Install gfortran and Open MPI on macOS using the Homebrew package manager. This also installs the necessary Xcode command-line tools.

```bash
brew install gfortran
brew install open-mpi
```

--------------------------------

### PARAMETERS file for initialization run

Source: https://www.viperleed.org/stable/_sources/content/calc/example_systems/Ag%28100%29.rst.txt

This PARAMETERS file is used for the initial ViPErLEED calculation, setting global parameters, POSCAR interpretation, and VIBROCC calculation settings.

```console
RUN = 0

# Energy range for calculation
THEO_ENERGIES = 45 700 3

# Parameters for interpreting POSCAR
BULK_LIKE_BELOW = 0.45
SITE_DEF Ag = surf 1

# Parameters for VIBROCC calculation
T_DEBYE = 220
T_EXPERIMENT = 295
VIBR_AMP_SCALE = 1.3

```

--------------------------------

### Install Test Dependencies

Source: https://www.viperleed.org/stable/_sources/content/appendix/notes_for_developers.rst.txt

Install test-related dependencies for ViPErLEED. Ensure you are in a clone of the repository.

```bash
python -m pip install --upgrade -r requirements/tests.txt
```

--------------------------------

### PARAMETERS File for Initialization Run

Source: https://www.viperleed.org/stable/content/calc/example_systems/Ag%28100%29.html

Configures ViPErLEED for an initial reference calculation. Sets global parameters, defines how to interpret the POSCAR structure, and specifies parameters for vibration calculations.

```text
! Comments can start with either ! or #

! ####### GLOBAL PARAMETERS #######
RUN = 0
THEO_ENERGIES = 45 700 3

! ####### PARAMETERS FOR INTERPRETING POSCAR #######
BULK_LIKE_BELOW = 0.45

SITE_DEF Ag = surf 1

! ####### PARAMETERS FOR VIBROCC #######
T_DEBYE = 330
T_EXPERIMENT = 100
VIBR_AMP_SCALE = *surf 1.3


```

--------------------------------

### Example: Fixed Oxygen Concentration

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/displacements/occdelta.rst.txt

This example shows how to fix the concentration of the oxygen atom to 80%, with the remainder being vacancies.

```text
= OCC_DELTA
O 1 = O 0.8                         ! Concentration of oxygen atom 1 (and symmetry-equivalent atoms) will be fixed to 80% (rest: vacancies)
```

--------------------------------

### Pipeline Example with POSCAR Utilities

Source: https://www.viperleed.org/stable/content/calc/utilities/poscar_utils.html

Demonstrates how to chain multiple POSCAR utilities using standard input and output for complex structure manipulation.

```bash
$ cat POSCAR | viperleed poscar delete_above C | viperleed poscar enforce_symmetry >POSCAR_OUT

```

--------------------------------

### Install Build Tools

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Installs essential build tools like cmake, pkg-config, and build-essential, which are required for compiling software.

```bash
sudo apt install cmake pkg-config build-essential -y
```

--------------------------------

### initialization

Source: https://www.viperleed.org/stable/content/api/sections/viperleed.calc.sections.initialization.html

Runs the initialization process for ViPErLEED calculations.

```APIDOC
## initialization

### Description
Runs the initialization.

### Parameters
- **sl** (object) - Description of the sl parameter is not provided in the source.
- **rp** (object) - Description of the rp parameter is not provided in the source.
- **subdomain** (object, optional) - Description of the subdomain parameter is not provided in the source.
```

--------------------------------

### Install ViPErLEED Python Package

Source: https://www.viperleed.org/stable/content/installation.html

Install the ViPErLEED package and command-line tools from PyPI using pip. This is the recommended method for most users.

```bash
python -m pip install viperleed

```

--------------------------------

### V0_REAL Syntax Examples

Source: https://www.viperleed.org/stable/content/calc/parameters/v0_real.html

Illustrates the basic syntax for defining the V0_REAL parameter using mathematical expressions involving electron energy (EE). Follows Fortran syntax rules.

```fortran
V0_REAL = -1*max(-10.17, -0.08 - 74.19/sqrt(EE+19.18))
V0_REAL = RUNDGREN -10.17 -0.08 -74.19 19.18
```

```fortran
V0_REAL = -1*max(c0,c1+c2/sqrt(EE+c3))
```

--------------------------------

### Install test dependencies

Source: https://www.viperleed.org/stable/content/appendix/notes_for_developers.html

Installs dependencies required for running ViPErLEED tests. Ensure you are in your local copy of the ViPErLEED GitHub repository.

```bash
python -m pip install --upgrade -r requirements/tests.txt

```

--------------------------------

### Install viperleed Package

Source: https://www.viperleed.org/stable/_sources/content/viperleed_calc.rst.txt

Install the viperleed package using pip. This command-line instruction is used to add the package to your Python environment.

```bash
pip install viperleed
```

--------------------------------

### Build Documentation

Source: https://www.viperleed.org/stable/_sources/content/appendix/notes_for_developers.rst.txt

Build the HTML documentation for ViPErLEED. Navigate to the 'doc' subfolder within your local repository clone.

```bash
make html
```

--------------------------------

### VIBROCC File Example

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/vibrocc.rst.txt

This example demonstrates the structure of a VIBROCC file, including sections for vibration amplitudes, occupations, and search offsets.

```text
  = Vibration Amplitudes
  M_def = Fe 0.1, Ni 0.1
  M_surf = Fe 0.125, Ni 0.12          !some comment
  O_def = 0.19
  O_surf = 0.18

  = Occupations
  M* = Fe 0.8, Ni 0.2
  O_surf = 0.95

  = Search offsets
  POS 4 = Fe 0.0 0.0 0.01, Ni 0.0 0.0 -0.01     ! PFe_def
  OCC 4 = Fe 0.01, Ni -0.01     ! PFe_def
```

--------------------------------

### RUN Parameter Syntax Examples

Source: https://www.viperleed.org/stable/content/calc/parameters/run.html

Demonstrates various ways to set the RUN parameter, including integer ranges, single integers, aliases, and combinations. Initialization (0) is always run. Indices 1-3 must be run in order. Index 4 is for domain calculations and has specific behavior.

```plaintext
RUN = 0-3 1
RUN = 0
RUN = ini     ! same as RUN = 0
RUN = 1       ! will automatically be changed to '0 1'
RUN = 0 3 1   ! runs initialization, search, and a final reference calculation. Requires pre-existing deltas.
RUN = ref-search ref   ! same as 1-3 1
```

--------------------------------

### IVBEAMS Input from BEAMLIST Example

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/ivbeams.rst.txt

Shows how beams can be copied from a BEAMLIST file into the IVBEAMS file, as columns beyond the first two are ignored.

```none
list of beams to output (input form: integer, float or fractions as 'a/b')
   1.00000   0.00000  1  1          E =     5.9289  NR.   4
   1.00000   1.00000  1  1          E =    11.0329  NR.   6
   1.00000  -1.00000  1  1          E =    11.0329  NR.   9
   0.00000   2.00000  1  1          E =    20.4162  NR.  10
   0.00000  -2.00000  1  1          E =    20.4162  NR.  11
   2.00000   0.00000  1  1          E =    23.7154  NR.  12
   1.00000   2.00000  1  1          E =    26.3450  NR.  14
   1.00000  -2.00000  1  1          E =    26.3450  NR.  17
   2.00000   1.00000  1  1          E =    28.8195  NR.  18
   2.00000  -1.00000  1  1          E =    28.8195  NR.  21
   2.00000   2.00000  1  1          E =    44.1316  NR.  22
   2.00000  -2.00000  1  1          E =    44.1316  NR.  25
   ...

```

--------------------------------

### DISPLACEMENTS File Structure Example

Source: https://www.viperleed.org/stable/content/calc/files/input/displacements.html

Illustrates the basic structure of the DISPLACEMENTS file with examples for geometric displacements, vibration amplitudes, and occupation variations.

```plaintext
= GEO_DELTA
O 1 z = -0.05 0.05 0.005      ! Oxygen atom 1 (and symmetry-equivalent atoms) will be displaced in z direction over the range [-0.05, 0.05] with step 0.005
Ir 2-11 z = -0.05 0.05 0.01   ! Iridium atoms 2-11 (and symmetry-equivalent atoms) will be displaced in z direction over the range [-0.05, 0.05] with step 0.01
O L(2-4) z = -0.05 0.05 0.01  ! Oxygen atoms in layers 2-4 will be displaced in z direction over the range [-0.05, 0.05] with step 0.01

= VIB_DELTA
O 1 = -0.05 0.05 0.02         ! Vibration amplitude of oxygen atom 1 (and symmetry-equivalent atoms) will be varied over the range [-0.05, 0.05] with step 0.02
Ir_top = -0.05 0.05 0.01      ! Vibration amplitude of Iridium atoms in Ir_top sites will be varied over the range [-0.05, 0.05] with step 0.01

= OCC_DELTA
O 1 = O 0.8 1.0 0.05          ! Concentration of oxygen atom 1 (and symmetry-equivalent atoms) will be varied from 80% to 100% with 5% steps (rest: vacancies)

```

--------------------------------

### ViPErLEED Initialization Log Output

Source: https://www.viperleed.org/stable/content/calc/example_systems/Ag%28100%29.html

Example log messages indicating successful initialization, symmetry detection, and unit cell identification by ViPErLEED.

```text
... 
Found unit cell type: square
Starting symmetry search...
Found plane group: p4m
Detected bulk repeat vector: [-1.44000 -1.44000 2.03647]
Checking bulk unit cell...
Found SUPERLATTICE = (1x1)
... 

```

--------------------------------

### Configuring SEARCH_START in viperleed.calc

Source: https://www.viperleed.org/stable/content/calc/parameters/searchstart.html

Sets the initial configuration for the search parameters. Allowed values include 'random', 'centered', 'control', and 'crandom'. If 'control' is selected and the control.chem file is missing, it defaults to 'crandom'.

```plaintext
SEARCH_START = control
```

--------------------------------

### Example PARAMETERS File Configuration

Source: https://www.viperleed.org/stable/content/calc/files/input/vibrocc.html

This snippet shows the configuration of ELEMENT_MIX and SITE_DEF parameters, which influence how VIBROCC entries are interpreted.

```plaintext
ELEMENT_MIX M = Fe Ni
SITE_DEF O = surf top(2)
SITE_DEF M = surf top(2)


```

--------------------------------

### Install LAPACK/BLAS Packages

Source: https://www.viperleed.org/stable/_sources/content/calc/install_tensor_leed.rst.txt

Install the built LAPACK and BLAS packages using pacman. Replace `<REPLACE_WITH_VERSION>` with the actual version number found in the directory.

```bash
pacman -U mingw-w64-x86_64-lapack-<REPLACE_WITH_VERSION>.pkg.tar.zst
```

--------------------------------

### Example Directory Tree for Domain Calculation Inputs

Source: https://www.viperleed.org/stable/content/calc/sections/domain_calculation.html

Illustrates a directory structure where input files for domains are located in separate directories. This allows for flexible input management.

```plaintext
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

```

--------------------------------

### IVBEAMS Input Format Example

Source: https://www.viperleed.org/stable/_sources/content/calc/files/input/ivbeams.rst.txt

Demonstrates the basic input format for the IVBEAMS file, accepting integers, floats, or fractions. Extra columns are ignored.

```none
list of beams to output (input form: integer, float or fractions as 'a/b')
1 0
0 -1
1 1
2 0
0 2
0.5 1
1 1/2
1/3 1
1/3 -1
```

--------------------------------

### Symmetry Detection Example

Source: https://www.viperleed.org/stable/content/api.html

This example demonstrates how to use the ViPErLEED API to load a slab from a POSCAR file, update parameters, and detect its plane group.

```APIDOC
## ViPErLEED Python API Example

### Description
This code snippet shows how to use the `viperleed` Python package to perform symmetry detection on a slab loaded from a POSCAR file.

### Usage
Import necessary modules, read a POSCAR file, initialize parameters, update the slab, and then find the plane group.

### Code Example
```python
from viperleed.calc import symmetry
from viperleed.calc.classes.rparams import Rparams
from viperleed.calc.files import poscar

# Load a slab from a POSCAR file
example_slab = poscar.read('POSCAR')

# Create an empty parameters object and update the slab
run_params = Rparams()
example_slab.full_update(run_params)

# Detect the plane group of the slab and print it
planegroup = symmetry.findSymmetry(example_slab, run_params)
print(planegroup)
```

### Modules Used
- `viperleed.calc.symmetry`
- `viperleed.calc.classes.rparams.Rparams`
- `viperleed.calc.files.poscar`
```

--------------------------------

### AVERAGE_BEAMS Syntax Examples

Source: https://www.viperleed.org/stable/content/calc/parameters/averagebeams.html

Demonstrates the various syntaxes for setting the AVERAGE_BEAMS parameter, including disabling averaging, simulating normal incidence, and specifying custom angles.

```plaintext
AVERAGE_BEAMS = off     ! ignore symmetry equivalence entirely. Alias: 'none', 'false'
```

```plaintext
AVERAGE_BEAMS = all     ! pretend that beam incidence is perpendicular (equivalent to setting '0 0'). Alias: 'perpendicular'
```

```plaintext
AVERAGE_BEAMS = 0 0     ! same as above
```

```plaintext
AVERAGE_BEAMS = THETA 0.3, PHI 10.1
```

```plaintext
AVERAGE_BEAMS = 0.3 10.1
```

--------------------------------

### Install Cairo Dependencies on macOS

Source: https://www.viperleed.org/stable/content/installation.html

Install necessary system dependencies for the `mplcairo` and `pycairo` packages on macOS using Homebrew. These are required for certain plotting functionalities.

```bash
brew install pkg-config cairo

```

--------------------------------

### Install ViPErLEED with Escaped GUI Dependencies (zsh)

Source: https://www.viperleed.org/stable/content/installation.html

Alternative method for zsh shell users to install ViPErLEED with GUI dependencies by escaping the square brackets.

```bash
python -m pip install viperleed\[GUI\]

```
Tokens:
Raw