Metadata-Version: 2.1
Name: excitingscripts
Version: 0.1.0
Summary: Executable command-line scripts for working with the exciting code.
Author: excitingscripts developers
Maintainer-email: Martin Kuban <kuban@physik.hu-berlin.de>, Mara Voiculescu <voiculem@physik.hu-berlin.de>
License: Copyright 2024 The excitingscripts developers
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
Project-URL: Source, https://github.com/exciting/exciting
Project-URL: Tutorials, https://exciting-code.org/home/tutorials
Classifier: Programming Language :: Python :: 3.7
Classifier: Operating System :: POSIX :: Linux
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy >=1.14.5
Requires-Dist: matplotlib >=2.2.0
Requires-Dist: scipy >=1.7.0
Requires-Dist: excitingtools >=1.6.3
Requires-Dist: typing-extensions ==3.10.0.2
Requires-Dist: ase >=3.22.1

# excitingscripts

**excitingscripts** is a collection of various python scripts for executing various tasks with the [`exciting`](https://exciting-code.org) code from
the command line.

## Installation

**excitingscripts** can be installed directly from PyPI:

```bash
pip install excitingscripts
```

Alternatively, it can be installed from the `exciting` source:

```bash
cd $EXCITINGROOT/tools/excitingscripts
pip install -e .
```

## Script Listing

### SETUP

#### <span style="color:#15317E">setup.band_structure</span>

Add band structure element to given input file by getting the band path from the input structure.

Located at `excitingscripts/setup/band_structure.py`.

Call as:

```bash
python3 -m excitingscripts.setup.band_structure
```

#### <span style="color:#15317E">setup.convergence_test</span>

Generate input files with different values of the main computational parameters.

Located at `excitingscripts/setup/convergence_test.py`.

Call as:

```bash
python3 -m excitingscripts.setup.convergence_test k_i k_f rgkmax_i rgkmax_f
```
Where <code>k_i</code> and <code>k_f</code> are the initial and final k-values for defining the 
<code><span style="color:green">groundstate</span></code> attribute 
<code><span style="color:MediumBlue">ngridk</span></code>, and <code>rgkmax_i</code> and <code>rgkmax_f</code> the 
initial and final values for the 
<code><span style="color:green">groundstate</span></code> attribute 
<code><span style="color:MediumBlue">rgkmax</span></code>.


#### <span style="color:#15317E">setup.dft_05</span>

Generate a set of input files varying the attribute <code><span style="color:mediumblue">cut</span></code>.

Located at `excitingscripts/setup/dft_05.py`.

Call as:

```bash
python3 -m excitingscripts.setup.dft_05 r_cut_min r_cut_max number_r_cut_steps -s species -r root_dir
```
Where <code>r_cut_min</code> and <code>r_cut_max</code> are the minimum and maximum values for r_cut, 
<code>number_r_cut_steps</code> is the number of r_cut values for which input files are generated, <code>species</code>
is the species with regard to which r_cut is varied and <code>root_dir</code> is the root directory.


#### <span style="color:#15317E">setup.dos_band_structure</span>

Add DOS and band structure element to given input file by getting the band path from the input structure.

Located at `excitingscripts/setup/dos_band_structure.py`.

Call as:

```bash
python3 -m excitingscripts.setup.dos_band_structure
```
#### <span style="color:#15317E">setup.excitingroot</span>

Replace placeholder "$EXCITINGROOT" in **input.xml** files by actual path.

Located at `excitingscripts/setup/excitingroot.py`.

Call as:

```bash
python3 -m excitingscripts.setup.excitingroot
```

#### <span style="color:#15317E">setup.interlayer_distance</span>

Generate structures with different interlayer distances.

Located at `excitingscripts/setup/interlayer_distance.py`.

Call as:

```bash
python3 -m excitingscripts.setup.interlayer_distance dmin dmax nr_displ dinfty
```
Where <code>dmin</code> and <code>dmax</code> are the minimum and maximum values for the interlayer distance, 
<code>nr_displ</code> is the number of distances in the interval [<code>dmin</code>, <code>dmin</code>] and
<code>dinfty</code> is the interlayer distance at infinity.

#### <span style="color:#15317E">setup.volume_optimization</span>

Generate structures at different volumes.

Located at `excitingscripts/setup/volume_optimization.py`.

Call as:

```bash
python3 -m excitingscripts.setup.volume_optimization nr_vol
```
Where <code>nr_vol</code> is the number of volume values for which structures are generated by varying the lattice
constant.

### EXECUTE

#### <span style="color:#15317E">execute.convergence_test</span>

Run a series of **exciting** calculations with different values of the main computational parameters.

Located at `excitingscripts/execute/convergence_test.py`.

Call as:

```bash
python3 -m excitingscripts.execute.convergence_test k_i k_f rgkmax_i rgkmax_f
```
Where <code>k_i</code> and <code>k_f</code> are the initial and final k-values for defining the 
<code><span style="color:green">groundstate</span></code> attribute 
<code><span style="color:MediumBlue">ngridk</span></code>, and <code>rgkmax_i</code> and <code>rgkmax_f</code> the 
initial and final values for the 
<code><span style="color:green">groundstate</span></code> attribute 
<code><span style="color:MediumBlue">rgkmax</span></code>.


#### <span style="color:#15317E">execute.elastic_strain</span>

Run a series of **exciting** calculations with different strain values.

Located at `excitingscripts/execute/elastic_strain.py`.

Call as:

```bash
python3 -m excitingscripts.execute.elastic_strain 
```

#### <span style="color:#15317E">execute.planar_average</span>

Extract planar-averaged electrostatic potential in a given direction.

Located at `excitingscripts/execute/planar_average.py`.

Call as:

```bash
python3 -m excitingscripts.execute.planar_average direction
```
Where <code>direction</code> is the direction along which the plane-averaged potential will be visualized.

#### <span style="color:#15317E">execute.single</span>

Run a single **exciting** calculation.

Located at `excitingscripts/execute/single.py`.

Call as:

```bash
python3 -m excitingscripts.execute.single -r rundir
```
Where <code>rundir</code> is an optional parameter which specifies the running directory.
If <code>rundir</code> is not specified, the calculation will run in the directory where the
script is called.

#### <span style="color:#15317E">execute.volume_optimization</span>

Run a series of **exciting** calculations for structures with different volumes.

Located at `excitingscripts/execute/volume_optimization.py`.

Call as:

```bash
python3 -m excitingscripts.execute.volume_optimization nr_vol
```
Where <code>nr_vol</code> is the number of volume values for which structures are generated by varying the lattice
constant.

### PLOT

#### <span style="color:#15317E">plot.band_structure</span>

Visualize band-structure.

More details can be found **[here](https://www.exciting-code.org/home/the-python-script-plot.band_structure)**.

Located at `excitingscripts/plot/band_structure.py`.

Call as:

```bash
python3 -m excitingscripts.plot.band_structure
```

#### <span style="color:#15317E">plot.compare_vdW</span>

Visualize multiple energy-vs-distance curves.

Located at `excitingscripts/plot/compare_vdW.py`.

Call as:

```bash
python3 -m excitingscripts.plot.compare_vdW -f file_name -r dir1 dir2 dir3
```

#### <span style="color:#15317E">plot.convergence</span>

Visualize convergence results.

Located at `excitingscripts/plot/convergence.py`.

Call as:

```bash
python3 -m excitingscripts.plot.convergence plot_mode
```
Where <code>plot_mode</code> is either <code>k</code> for plotting energy curves with varying values of the <code><span style="color:green">groundstate</span></code> attribute 
<code><span style="color:MediumBlue">ngridk</span></code>, <code>r</code> for varying values of the 
<code><span style="color:green">groundstate</span></code> attribute 
<code><span style="color:MediumBlue">rgkmax</span></code> or 
<code>rk</code> for a 3D plot with varying values of both attributes.

#### <span style="color:#15317E">plot.dos</span>

Visualize desisty of states.

More details can be found **[here](https://www.exciting-code.org/home/the-python-script-plot.dos)**.

Located at `excitingscripts/plot/dos.py`.

Call as:

```bash
python3 -m excitingscripts.plot.dos
```

#### <span style="color:#15317E">plot.energy</span>

Visualize energy-vs-strain curves.

Located at `excitingscripts/plot/energy.py`. 

Call as:

```bash
python3 -m excitingscripts.plot.energy
```

#### <span style="color:#15317E">plot.exciton_weights</span>

Visualize energy-vs-strain curves.

Located at `excitingscripts/plot/exciton_weights.py`. 

Call as:

```bash
python3 -m excitingscripts.plot.exciton_weights structure_name file_name energy_min energy_max exciton_weights_size
```
Where <code>structure_name</code> is the name of the structure, <code>file_name</code> is the name of the file
containing data needed for exciton visualization, <code>energy_min</code> and <code>energy_max</code> are the minimum
and maximum energy values for setting plot axis limits, and <code>exciton_weights_size</code> is the size of excitonic
weights.

#### <span style="color:#15317E">plot.files</span>

Visualize data included in different files and different directories.

More details can be found **[here](https://www.exciting-code.org/home/the-python-script-plot.files)**.

Located at `excitingscripts/plot/files.py`. 

Call as:

```bash
python3 -m excitingscripts.plot.files
```

#### <span style="color:#15317E">plot.newbirch</span>

Fit energy-vs-volume curves using the Birch-Murnaghan equation of state (**BM-EoS**) in polynomial form.

Located at `excitingscripts/plot/newbirch.py`.

Call as:

```bash
python3 -m excitingscripts.plot.newbirch
```
#### <span style="color:#15317E">plot.spintext</span>

Produce plot of the spin texture.

Located at `excitingscripts/plot/spintext.py`.

Call as:

```bash
python3 -m excitingscripts.plot.spintext -b ib -c context 
```
Where <code>ib</code> defines the band index for the plot and <code>context</code> defines the context of the contour
plot. Choises are <code>energy</code> and <code>spin_z</code>.

#### <span style="color:#15317E">plot.volumecurves</span>

Fit energy-vs-volume curves.

Located at `excitingscripts/plot/volumecurves.py`.

Call as:

```bash
python3 -m excitingscripts.plot.volumecurves -r dir1 dir2 dir3
```
Where <code>dir1</code>, <code>dir2</code>, <code>dir3</code> take the place of the names of the  directories where
exciting calculations have been performed. The script can be used for any number of directories.

### Other Scripts

#### <span style="color:#15317E">compare_transition_energies</span>

Determine the transition energies for the transitions Γ→Γ and Γ→X for given directories in which exciting
calculations have been performed.

Located at `excitingscripts/compare_transition_energies.py`.

Call as:

```bash
python3 -m excitingscripts.compare_transition_energies -r dir1 dir2 dir3
```
Where <code>dir1</code>, <code>dir2</code>, <code>dir3</code> take the place of the names of the  directories where
exciting calculations have been performed, which need to be specified in order to calculate the transition energies.
The script can be used for any number of directories.

#### <span style="color:#15317E">convert_xml2xsf</span>

Convert **xml** files to **xsf**.

Located at `excitingscripts/convert_xml2xsf.py`.

Call as:

```bash
python3 -m excitingscripts.convert_xml2xsf -f file -d dimension
```
Where <code>file</code> is the **xml** file to be converted to **xsf** and <code>dimension</code> is the dimension of
<code><span style="color:green">plot</span></code> sub-element in the
<code><span style="color:green">properties</span></code> element for a given exciting calculation.
