### Strain Class Initialization Example 1: Using Reference System

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.8._Strain_class.html

This example demonstrates initializing the Strain class using a reference system to construct p_vectors. It requires the system to be analyzed, a reference system, and a cutoff distance for neighbor list generation.

```APIDOC
## Initialize Strain Class - Example 1

### Description
Initializes the Strain class using a reference system to define p_vectors.

### Method
```python
am.defect.Strain(system, basesystem=None, baseneighbors=None, neighbors=None, cutoff=None, p_vectors=None, axes=None, theta_max=27.0)
```

### Parameters

*   **system** (_atomman.System_): The atomic system to compute strain properties for.
*   **basesystem** (_atomman.System_): A reference atomic system for constructing p_vectors.
*   **cutoff** (_float_): Cutoff distance for computing neighbor list for `basesystem` if `baseneighbors` is not provided.

### Request Example
```python
import atomman as am
import numpy as np

# Load systems
base_system = am.load('atom_dump', 'files/fcc_Al_base.dump')
disl_system = am.load('atom_dump', 'files/fcc_Al_disl.dump')

alat = 4.05

# Initialize Strain class using basesystem and cutoff
strain = am.defect.Strain(disl_system, basesystem=base_system, cutoff=0.9*alat)

# Accessing computed p_vectors for the first atom
print(strain.p_vectors[0])
```

### Response Example
```
[[ 0.          2.86378576  0.        ]
 [-2.48011122  1.43189288  0.        ]
 [ 2.48011122 -1.43189288  0.        ]
 [ 2.48011122  1.43189288  0.        ]
 [ 1.65340748  0.         -2.33827128]
 [-0.82670374 -1.43189288 -2.33827128]
 [-0.82670374  1.43189288 -2.33827128]
 [ 0.         -2.86378576  0.        ]
 [-2.48011122 -1.43189288  0.        ]
 [-1.65340748  0.          2.33827128]
 [ 0.82670374  1.43189288  2.33827128]
 [ 0.82670374 -1.43189288  2.33827128]]
```
```

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

### Displacement output example

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/3._Basic_support_and_analysis_tools.html

Example output showing the vector differences between atoms.

```text
[[2.39315582e+00 1.93285757e+00 2.62930773e+00]
 [1.70693199e+00 1.67755942e+00 4.46071098e-01]
 [1.83643203e+00 2.96721168e+00 1.74986897e+00]
 [9.68122262e-01 1.77011698e+00 1.03883896e+00]
 [7.19742667e-01 2.36355181e+00 8.86329527e-01]
 [5.45578861e-01 1.51298915e+00 9.58368954e-01]
 [2.58746893e+00 2.43101206e+00 2.22457166e+00]
 [1.16413297e+00 1.97065000e+00 2.78419884e+00]
 [6.85733642e-01 2.63582318e+00 1.55820432e+00]
 [2.15125684e+00 2.71790059e+00 1.05802562e+00]
 [2.47112179e-01 1.08105801e+00 4.23841004e-01]
 [1.86704329e+00 2.01581120e+00 1.01125816e+00]
 [5.72542380e-01 2.94214296e-01 1.34988394e+00]
 [1.52910691e+00 1.58582017e+00 2.37563107e+00]
 [1.74765534e-01 2.40611978e+00 1.36171703e+00]
 [2.26195277e+00 2.29335455e+00 6.30815064e-01]
 [2.01659168e+00 2.42895666e+00 1.63780516e+00]
 [1.10690501e+00 1.07315550e+00 2.94325138e+00]
 [1.26813155e+00 2.35461542e+00 1.30290216e+00]
 [2.23208893e+00 2.35568387e+00 1.38191313e+00]
 [8.03141909e-01 4.68669770e-01 2.30863006e+00]
 [9.69786434e-01 2.17070593e+00 8.83004993e-01]
 [2.64106916e+00 1.44931436e-03 1.13862900e+00]
 [1.04577933e+00 1.86609396e+00 1.23122119e+00]
 [2.21698769e+00 2.67205670e+00 6.65136655e-02]
 [2.11785460e-01 7.32292912e-01 2.56925160e+00]
 [2.74423006e+00 2.43172841e-01 1.14877798e+00]
 [2.08404682e+00 1.96232221e+00 1.85404217e+00]
 [3.60658551e-01 4.66987696e-01 2.47290750e+00]
 [1.94660925e+00 2.45659821e+00 8.67397975e-01]
 [1.78263433e+00 1.50934818e+00 1.65823051e+00]
 [2.55145130e+00 2.49019416e-01 2.18769565e+00]
 [1.40769026e+00 5.79803116e-02 2.88072842e+00]
 [1.75369282e+00 1.67203177e+00 1.47998012e+00]
 [2.19144508e+00 1.29803453e+00 5.58358633e-01]
 [1.26125531e+00 2.14322673e+00 6.70412330e-01]
 [1.60899869e+00 1.05557449e+00 1.86570279e+00]
 [1.70334504e+00 2.18144488e+00 1.92454559e+00]
 [2.09532232e+00 3.09290869e-01 1.86830451e+00]
 [1.87947882e+00 2.97306530e-01 1.29360306e+00]
 [5.87217512e-01 1.06077965e+00 2.38945799e+00]
 [1.37511304e+00 8.86015737e-02 1.76798507e-01]
 [2.77128283e+00 2.03813406e+00 1.31166355e+00]
 [2.20996054e-01 1.97906751e-02 4.20765266e-01]
 [2.70952990e-01 7.65542891e-01 4.84299731e-01]
 [2.28116297e+00 2.01509415e-01 2.48917275e+00]
 [1.82585953e+00 9.69371397e-01 1.28094488e+00]
 [2.59050294e+00 1.47419654e-01 7.06910218e-01]
 [1.30984808e+00 2.61397189e+00 2.72344953e+00]
 [2.74652851e+00 1.58209073e+00 1.57836668e+00]
 [1.43679801e+00 2.24145701e+00 1.32871416e+00]
 [4.99357678e-01 1.04315152e+00 1.41268256e+00]
 [1.33140686e+00 7.31645886e-01 3.44785594e-01]
 [2.42620345e+00 1.00698349e+00 2.12021083e+00]
 [2.06075608e+00 1.35857464e+00 2.14829359e+00]
 [1.68586009e+00 1.60005374e+00 2.31917278e+00]
 [1.27076902e+00 1.96760602e+00 7.24606935e-01]
 [1.13550297e+00 6.26264775e-02 8.56941760e-01]
 [1.54403223e-01 2.58627534e+00 2.25170839e+00]
 [2.55208173e+00 6.11658215e-01 4.66556435e-02]
 [1.40389684e+00 2.86906306e-01 1.31441216e+00]
 [2.88703390e+00 6.13323665e-01 2.35789525e+00]
 [1.18281832e+00 7.09588218e-01 2.44792041e+00]
 [1.61392296e+00 9.84809705e-01 6.89592295e-01]]
```

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

### Import atomman and show version

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/0._Unit_conversions.html

Imports necessary libraries and prints the atomman version and the date of execution. Ensure atomman is installed.

```python
# Standard Python libraries
import datetime

# http://www.numpy.org/
import numpy as np

# https://github.com/usnistgov/atomman
import atomman as am
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())

```

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

### Atomman Version and Execution Date

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.12._DFT_reference_crystal_loading.html

Displays the installed atomman version and the date the notebook was executed. This is a confirmation output.

```text
atomman version = 1.4.11
Notebook executed on 2024-04-29

```

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

### LAMMPS Input Script Example

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/2._LAMMPS_functionality.html

This is an example of a LAMMPS input script generated by atomman, including system setup, potential definition, thermodynamic variables, and simulation run commands.

```lammps
units metal
atom_style atomic

boundary p p p
read_data atom.dat

print "Potential 2015--Pascuet-M-I--Al--LAMMPS--ipr1 listed in the NIST Interatomic Potentials Repository:"
print "https://www.ctcms.nist.gov/potentials/entry/2015--Pascuet-M-I-Fernandez-J-R--Al/2015--Pascuet-M-I--Al--LAMMPS--ipr1.html"
print "Publication(s) related to the potential:"
print "https://doi.org/10.1016/j.jnucmat.2015.09.030"
print "Parameter file(s) can be downloaded at:"
print "https://www.ctcms.nist.gov/potentials/Download/2015--Pascuet-M-I-Fernandez-J-R--Al/1/Al.meam"
print "https://www.ctcms.nist.gov/potentials/Download/2015--Pascuet-M-I-Fernandez-J-R--Al/1/library-Al.meam"
pair_style meam
pair_coeff * * library-Al.meam Al Al.meam Al
mass 1 26.9815



# Define temperature and dependent variables
variable T equal 100
variable twoT equal 2*$T

# Define equilibrium pressure
variable P equal 0.0

# Define timestep and dependent variables
variable deltat equal 0.001
variable Trelax equal 100*${deltat}
variable Prelax equal 1000*${deltat}

# Initialize atomic velocities with twoT
velocity all create ${twoT} 124352

# Define thermo steps and properties
thermo 100
thermo_style custom step temp press lx ly lz

# Define dump
dump mydump all atom 100000 *.dump

# Specify timestep
timestep ${deltat}

# Apply npt conditions
fix 1 all npt temp $T $T ${Trelax} iso $P $P ${Prelax}

# Run simulation
run 100000

```

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

### Create a System object

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1._Defining_atomic_systems.html

Initializes a new System by combining atoms, box dimensions, periodic boundary conditions, and element symbols.

```python
system = am.System(atoms=atoms, box=box, pbc=[True, False, True], symbols='Al', scale=True)
print(system)
```

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

### Dump system with modified parameters

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.5._LAMMPS_data_file_conversions.html

This example shows how to dump the system data while modifying 'units', 'natypes', and 'atom_style' parameters. It also demonstrates how to set per-atom properties like 'charge' when required by the chosen atom_style.

```python
# atom_style='charge' requires per-atom property charge to be set
system.atoms.charge = 0

# units='nano' will return pos in nm instead of Angstroms
# natypes=2 only changes the atom types header
info = system.dump('atom_data', f='bccFe.dat', units='nano', natypes=2, atom_style='charge')
```

```python
with open('bccFe.dat') as f:
    print(f.read())
```

```python
print(info)
```

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

### GET /retrieve_crystal_prototype

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.library.Database.html

Gets a single matching crystal prototype from the database and saves it to a file.

```APIDOC
## GET /retrieve_crystal_prototype

### Description
Gets a single matching crystal prototype from the database and saves it to a file based on the record’s name.

### Method
GET

### Endpoint
/retrieve_crystal_prototype

### Parameters
#### Query Parameters
- **name** (str | list) - Optional - The name(s) of records to limit the search by.
- **dest** (Path) - Optional - Destination path for the saved file.
- **id** (str | list) - Optional - Record ID.
- **key** (str | list) - Optional - Record UUID4 key.
- **commonname** (str | list) - Optional - Common name of the prototype.
- **prototype** (str | list) - Optional - Prototype identifier.
- **pearson** (str | list) - Optional - Pearson symbol.
- **strukturbericht** (str | list) - Optional - Strukturbericht designation.
- **sg_number** (int | list) - Optional - Space group number.
- **sg_hm** (str | list) - Optional - Hermann-Mauguin space group symbol.
- **sg_schoenflies** (str | list) - Optional - Schoenflies space group symbol.
- **crystalfamily** (str | list) - Optional - Crystal family.
- **natypes** (int | list) - Optional - Number of unique atom types.
- **local** (bool) - Optional - Search local database.
- **remote** (bool) - Optional - Search remote database.
- **prompt** (bool) - Optional - Prompt for confirmation.
- **format** (str) - Optional - File format (default 'json').
- **indent** (int) - Optional - Indentation for output file.
- **refresh_cache** (bool) - Optional - Refresh metadata cache.
- **verbose** (bool) - Optional - Print info messages.
```

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

### Importing atomman and standard libraries

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.1._Box_class.html

Initializes the environment by importing necessary libraries and displaying the current atomman version.

```python
# Standard Python libraries
import datetime

# http://www.numpy.org/
import numpy as np

# https://github.com/usnistgov/atomman
import atomman as am
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())
```

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

### Example Output of Burgers Vector Comparison

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.8._Strain_class.html

Example output showing the comparison between the actual and estimated Burgers vectors.

```text
actual Burgers vector:    [ 0.0000,  2.8638,  0.0000]
estimated Burgers vector: [-0.0041,  2.9144,  0.0015]
```

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

### System Class Initialization

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.System.html

Information on how to initialize a System object.

```APIDOC
## System Class

### Description
A representation of an atomic system. This combines Atoms with Box and adds methods and attributes involving both.

### Parameters
- **_atoms** (Atoms | None) - Optional - Underlying Atoms object.
- **_box** (Box | None) - Optional - Underlying Box object.
- **_pbc** (Tuple[bool, bool, bool] | None) - Optional - Periodic boundary conditions.
- **_scale** (bool) - Optional - Flag indicating if positions are scaled.
- **_symbols** (str | list | None) - Optional - Symbols for the atoms.
- **_masses** (float | list | None) - Optional - Masses for the atoms.
- **_model** (str | IOBase | DataModelDict | None) - Optional - Model for the system.
- **_safecopy** (bool) - Optional - Flag indicating if values are to be copied before setting.
```

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

### Install atomman using pip

Source: https://www.ctcms.nist.gov/potentials/atomman/index.html

Install the latest release of the atomman package using pip. Ensure you are using Python 3.7 or newer.

```bash
pip install atomman
```

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

### Initialize atomman environment

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.1._Point_defect_generation.html

Import necessary libraries and display the current atomman version and execution date.

```python
# Standard libraries
import datetime

# http://www.numpy.org/
import numpy as np

# https://github.com/usnistgov/atomman
import atomman as am
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())
```

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

### Install atomman using conda

Source: https://www.ctcms.nist.gov/potentials/atomman/index.html

Alternatively, install atomman using conda from the conda-forge channel. This method is recommended for users who prefer the Anaconda distribution.

```bash
conda install atomman -c conda-forge
```

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

### Importing standard libraries and atomman

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.13._primitive_cell_dumping.html

Initializes the environment by importing necessary libraries and displaying the current atomman version and execution date.

```python
# Standard Python libraries
import datetime

# http://www.numpy.org/
import numpy as np

import atomman as am
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())
```

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

### Import Libraries and Show Version

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.8._Strain_class.html

Imports necessary Python libraries for atomman, NumPy, and Matplotlib, and displays the installed atomman version and the date of execution. Ensure these libraries are installed before running.

```python
# Standard Python libraries
import os
import datetime
import time

# http://www.numpy.org/
import numpy as np

# https://github.com/usnistgov/atomman
import atomman as am
import atomman.unitconvert as uc

# https://matplotlib.org/
import matplotlib.pyplot as plt
%matplotlib inline

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())

```

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

### Initialize SDVPN Object

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.7._Semidiscrete_variational_Peierls-Nabarro_model.html

Configures minimization options and initializes the SDVPN object using the Volterra solution and gamma surface.

```python
min_options = {}
min_options['disp'] = True     # will display convergence info
min_options['xtol'] = 1e-6     # smaller convergence tolerance than default
min_options['ftol'] = 1e-6     # smaller convergence tolerance than default
#min_options['maxiter'] = 2    # for testing purposes

# Initialize SDVPN object from volterra and gamma
pnsolution = am.defect.SDVPN(volterra=volterra, gamma=gamma, min_options=min_options)
```

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

### Strain Class Initialization Example 2: Using Explicit p_vectors and Axes

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.8._Strain_class.html

This example shows how to initialize the Strain class by providing explicit p_vectors and transformation axes. This method is useful when the reference state is known or defined separately.

```APIDOC
## Initialize Strain Class - Example 2

### Description
Initializes the Strain class by providing explicit p_vectors and transformation axes.

### Method
```python
am.defect.Strain(system, neighbors=None, cutoff=None, p_vectors=None, axes=None, theta_max=27.0)
```

### Parameters

*   **system** (_atomman.System_): The atomic system to compute strain properties for.
*   **neighbors** (_atomman.NeighborList_): Pre-computed neighbor list for the `system`.
*   **p_vectors** (_array-like object_): Explicit list(s) of radial distance vectors.
*   **axes** (_array-like object_): 3x3 array of right-handed orthogonal axes for transforming p_vectors.

### Request Example
```python
import atomman as am
import numpy as np

# Load system
disl_system = am.load('atom_dump', 'files/fcc_Al_disl.dump')
alat = 4.05

# Compute neighbors beforehand
neighbors = disl_system.neighborlist(cutoff=0.9*alat)

# Define p_vectors for fcc cubic (standard reference frame)
p_vectors = alat * np.array([[ 0.5, 0.5, 0.0], [ 0.5, 0.0, 0.5], [ 0.0, 0.5, 0.5],
                             [-0.5, 0.5, 0.0], [-0.5, 0.0, 0.5], [ 0.0,-0.5, 0.5],
                             [ 0.5,-0.5, 0.0], [ 0.5, 0.0,-0.5], [ 0.0, 0.5,-0.5],
                             [-0.5,-0.5, 0.0], [-0.5, 0.0,-0.5], [ 0.0,-0.5,-0.5]])

# Define the transformation axes
xaxis = [-1,-1, 2]
yaxis = [ 1,-1, 0]
zaxis = [ 1, 1, 1]
axes = am.tools.axes_check([xaxis, yaxis, zaxis])

# Initialize Strain class with explicit p_vectors and axes
strain = am.defect.Strain(disl_system, neighbors=neighbors, p_vectors=p_vectors, axes=axes)

# Accessing computed p_vectors for the first atom
print(strain.p_vectors[0])
```

### Response Example
```
[[-1.65340558  0.          2.33826859]
 [ 0.82670279  1.43189123  2.33826859]
 [ 0.82670279 -1.43189123  2.33826859]
 [ 0.         -2.86378246  0.        ]
 [ 2.48010836 -1.43189123  0.        ]
 [ 2.48010836  1.43189123  0.        ]
 [ 0.          2.86378246  0.        ]
 [-2.48010836  1.43189123  0.        ]
 [-2.48010836 -1.43189123  0.        ]
 [ 1.65340558  0.         -2.33826859]
 [-0.82670279 -1.43189123 -2.33826859]
 [-0.82670279  1.43189123 -2.33826859]]
```
```

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

### Importing standard libraries and atomman

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.5._LAMMPS_data_file_conversions.html

Initializes the environment by importing necessary Python libraries and the atomman package.

```python
# Standard Python libraries
import os
import datetime

# http://www.numpy.org/
import numpy as np

import atomman as am
import atomman.lammps as lmp
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())
```

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

### Generate Supercell using supersize()

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.3._System_class.html

Demonstrates how to create a supercell of an existing system using the `supersize()` method.

```APIDOC
## 5.4. supersize()

### Description
A supercell version of a system can be generated using the supersize() method.

### Parameters
  * **a_size** (_int or tuple of int_) size multipliers for the system along the a box vector.
  * **b_size** (_int or tuple of int_) size multipliers for the system along the b box vector.
  * **c_size** (_int or tuple of int_) size multipliers for the system along the c box vector.

### Returns
  * (_atomman.System_) a new System constructed by replicating the original along its box vectors.

All three size terms can be positive or negative integers, or a tuple of (negative, positive) integers. Negative values replicate the system below the origin and positive values replicate the system above the origin.

### Example
```python
# Create 2x2x2 supercell
# new avect will start at the old origin
a_size = 2

# new bvect will end at the old origin
b_size = -2

# Assuming 'system' is a pre-defined atomman.System object
# supercell = system.supersize(a_size=a_size, b_size=b_size)
```
```

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

### GET /itercoords

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.cluster.BondAngleMap.html

Iterates through the three-body coordinates of the cluster.

```APIDOC
## GET /itercoords

### Description
Iterates through the three-body coordinates, which can be used as inputs for computing energies.

### Response
#### Success Response (200)
- **r_ij** (float) - The radial distance between atoms i and j.
- **r_ik** (float) - The radial distance between atoms i and k.
- **r_jk** (float) - The radial distance between atoms j and k.
- **theta** (float) - The angle between i-j and i-k in degrees.
```

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

### Initializing a default System

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.3._System_class.html

Creates a System object using default Atoms and Box parameters.

```python
system = am.System()

print(system)
```

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

### GET /strain/asdict

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.8._Strain_class.html

Returns the computed strain properties as a dictionary.

```APIDOC
## GET /strain/asdict

### Description
Returns a dictionary containing the computed properties.

### Parameters
#### Query Parameters
- **properties** (str or list) - Optional. List of properties to include in the dictionary. Defaults to [strain, invariant1, invariant2, invariant3, angularvelocity, nye].
```

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

### atomman.load()

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4._Load_and_dump_conversions.html

Creates a System object from a specified format style and content.

```APIDOC
## atomman.load()

### Description
Creates a System object based on another representation.

### Parameters
#### Arguments
- **style** (str) - Required - Indicates the format of the content being loaded.
- **content** (any) - Required - The content to be loaded. For text formats, can be a str of the content, a file path or a file-like object.
- **kwargs** (any) - Optional - Any extra style-specific keyword arguments.
```

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

### GET /nonlocal_energy

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.defect.SDVPN.html

Computes the nonlocal energy correction for the dislocation.

```APIDOC
## GET /nonlocal_energy

### Description
Computes the nonlocal energy correction using alpha coefficient(s).

### Method
GET

### Endpoint
/nonlocal_energy

### Parameters
#### Query Parameters
- **x** (array-like) - Optional - x-coordinates. Default is the stored x-coordinates.
- **disregistry** (array-like) - Optional - (N, 3) shaped array of disregistry vectors. Default is the stored disregistry values.

### Response
#### Success Response (200)
- **energy** (float) - The nonlocal energy for the dislocation.
```

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

### Import Libraries and Show Version

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.15._pdb_dumping.html

Imports necessary libraries and prints the atomman version and notebook execution date. Ensure atomman is installed.

```python
# Standard Python libraries
import datetime

# http://www.numpy.org/
import numpy as np

import atomman as am
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())

```

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

### Atomman Y Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'Y' in the Atomman library.

```APIDOC
## Y
  * yhi (atomman.Box property)
  * ylo (atomman.Box property)
  * yz (atomman.Box property)
```

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

### Load a database prototype

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1._Defining_atomic_systems.html

Creates a system from a crystal prototype stored in the potentials database by specifying the element and lattice constants.

```python
potdb = am.library.Database()
```

```python
print(potdb.local_database)
```

```python
new_system = am.load('prototype', name='A1--Cu--fcc', a=4.05, symbols='Al')
print(new_system)
```

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

### GET /atomman/system/properties

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Retrieves system-level properties such as atom counts and types.

```APIDOC
## GET /atomman/system/properties

### Description
Retrieves core properties of an atomman.System or atomman.Atoms object, including the number of atoms and atom types.

### Method
GET

### Endpoint
/atomman/system/properties

### Response
#### Success Response (200)
- **natoms** (int) - Total number of atoms in the system.
- **natypes** (int) - Total number of atom types in the system.
```

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

### GET /atomman/defect/slip_vector

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.defect.html

Compute the slip vectors for all atoms between two systems.

```APIDOC
## GET /atomman/defect/slip_vector

### Description
Compute the slip vectors for all atoms. Note that this differs from the original formulation in that it is not normalized by number of slipped neighbors.

### Parameters
#### Query Parameters
- **system_0** (atomman.system) - Required - The base/reference system to use.
- **system_1** (atomman.system) - Required - The defect/current system to use.
- **neighbors** (atomman.NeighborList) - Optional - The neighbor list associated with system_0.
- **cutoff** (float) - Optional - Cutoff distance for computing a neighbor list for system_0.

### Response
#### Success Response (200)
- **slip_vectors** (numpy.ndarray) - The computed slip vectors.
```

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

### Build free surface configuration

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4.3._Stacking_fault_generator.html

Generates a system with a vacuum region for surface calculations.

```python
surfacesystem = sf.surface(shift=sf.shifts[0], minwidth=15, even=True, vacuumwidth=20)
print(surfacesystem)
```

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

### Atomman T Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'T' in the Atomman library.

```APIDOC
## T
  * tau (atomman.defect.SDVPN property)
  * tetragonal() (atomman.Box class method)
    * (atomman.ElasticConstants method)
  * theta() (atomman.defect.IsotropicVolterraDislocation method)
  * theta_max (atomman.defect.Strain property)
  * thetamax (atomman.cluster.BondAngleMap property)
  * thetamin (atomman.cluster.BondAngleMap property)
  * thetanum (atomman.cluster.BondAngleMap property)
  * timestep() (in module atomman.lammps.style)
  * tol (atomman.defect.VolterraDislocation property)
  * total_energy() (atomman.defect.SDVPN method)
  * transform (atomman.defect.Dislocation property)
    * (atomman.defect.FreeSurface property)
    * (atomman.defect.SDVPN property)
    * (atomman.defect.VolterraDislocation property)
  * transform() (atomman.ElasticConstants method)
  * triclinic() (atomman.Box class method)
    * (atomman.ElasticConstants method)
  * trigonal() (atomman.Box class method)
```

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

### Initialize atomman environment

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/2.2._Running_LAMMPS_and_the_Log_class.html

Imports necessary libraries and initializes the atomman environment for simulation tasks.

```python
# Standard libraries
import os
import glob
import time
import datetime

# http://matplotlib.org/
import matplotlib.pyplot as plt
%matplotlib inline

# https://github.com/usnistgov/atomman
import atomman as am
import atomman.lammps as lmp
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())
```

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

### Define potential branch structure

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/2.1._Potential_class.html

Example of the potential metadata branch structure.

```python
print("""{ "potential": { "key": <uuid>, "id": <name> } }""")
```

```json
{
    "potential": {
        "key": <uuid>,
        "id": <name>
    }
}
```

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

### Initialize System with Random Atomic Positions

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.3._System_class.html

Creates a system with 10 atoms placed at random positions between 0 and 10, within a box of dimensions 1x1x1. This is a setup for demonstrating the wrap() method.

```python
# Generate ten atom system with atoms between 0 and 10 and box boundaries 0 and 1
system = am.System(atoms=am.Atoms(pos=10*np.random.rand(10,3)))
print(system)
```

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

### GET /DifferentialDisplacement/plot_with_nye

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.defect.DifferentialDisplacement.html

Generates a differential displacement plot with the Nye tensor calculation.

```APIDOC
## GET /DifferentialDisplacement/plot_with_nye

### Description
Generates a differential displacement plot and calculates the Nye tensor over the plotted area.

### Method
GET

### Parameters
#### Query Parameters
- **matplotlib_axes** (matplotlib.Axes.axes) - Optional - An existing matplotlib axes object to add the plot to.

### Response
#### Success Response (200)
- **sum** (float) - The integer sum of the Nye tensor over the plotted area.
- **figure** (matplotlib.Figure) - The generated figure.
```

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

### GET /shear

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.ElasticConstants.html

Returns a shear modulus estimate based on the specified style.

```APIDOC
## GET /shear

### Description
Returns a shear modulus estimate.

### Parameters
#### Query Parameters
- **style** (str) - Required - Indicates which style of estimate to use. Default is 'Hill'. Options: 'Hill', 'Voigt', 'Reuss'.
```

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

### Load POSCAR file with atomman

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/index.html

Demonstrates loading a POSCAR file into an Atomman System object. Ensure the POSCAR file is correctly formatted.

```python
import atomman
system = atomman.load('poscar', 'POSCAR')
```

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

### Atomman Xi Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'Ξ' in the Atomman library.

```APIDOC
## Ξ
  * ξ (atomman.defect.VolterraDislocation property)
```

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

### Creating a bcc demonstration supercell

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/4._Defect_creation_and_analysis.html

Sets up a 2x2x2 bcc supercell using atomman's Box and System classes.

```python
# Define 2x2x2 bcc demonstration supercell
a = uc.set_in_units(2.8665, 'angstrom')
box = am.Box(a=a, b=a, c=a)
atoms = am.Atoms(atype=1, pos=[[0.0,0.0,0.0], [0.5,0.5,0.5]])
ucell = am.System(atoms=atoms, box=box, scale=True)
system = ucell.supersize(2,2,2)
print(system.atoms_df())
```

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

### Initialize System with a Model

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.1._system_model_conversions.html

Initializes a new System object using an existing model. The model can be a DataModelDict, a JSON string, an XML string, or a file path to a JSON or XML file.

```python
# Initialize new system using model
system2 = am.System(model=model)
```

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

### Atomman Z Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'Z' in the Atomman library.

```APIDOC
## Z
  * zhi (atomman.Box property)
  * zlo (atomman.Box property)
```

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

### Class Initialization and Factory Methods

Source: https://www.ctcms.nist.gov/potentials/atomman/atomman.Box.html

Methods for creating a new Box instance, including factory methods for specific crystal systems.

```APIDOC
## POST /Box/cubic

### Description
Initializes a Box in standard cubic setting using only cubic lattice parameters (a = b = c, alpha = beta = gamma = 90).

### Parameters
#### Request Body
- **a** (float) - Required - The a lattice constant

## POST /Box/hexagonal

### Description
Initializes a Box in standard hexagonal setting using only hexagonal lattice parameters (a = b != c, alpha = beta = 90, gamma = 120).

### Parameters
#### Request Body
- **a** (float) - Required - The a lattice constant
- **c** (float) - Required - The c lattice constant
```

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

### Atomman X Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'X' in the Atomman library.

```APIDOC
## X
  * x (atomman.defect.SDVPN property)
  * xhi (atomman.Box property)
  * xlo (atomman.Box property)
  * xy (atomman.Box property)
  * xy_to_a12() (atomman.defect.GammaSurface method)
  * xy_to_pos() (atomman.defect.GammaSurface method)
  * xz (atomman.Box property)
```

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

### atomman.load('dft_reference', 'mp-81')

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.4.12._DFT_reference_crystal_loading.html

This snippet demonstrates how to load a crystal prototype from the Materials Project database using its ID and an API key. It also shows how to enable verbose output for more detailed information during the loading process. The example includes error handling for a common MPRestError related to API key issues.

```APIDOC
## POST /api/load/dft_reference

### Description
Accesses the potentials database to retrieve a crystal_prototype record and generate a unit cell System based on it. This specific example focuses on loading from the 'dft_reference' style, likely corresponding to Materials Project.

### Method
POST (implied by database loading operations)

### Endpoint
/api/load/dft_reference

### Parameters
#### Query Parameters
- **id** (str) - Required - The reference crystal’s unique id. Combines a database tag “mp-” or “oqmd-” and the DFT database’s entry id. For example: 'mp-81'.
- **api_key** (str, optional) - The user’s Materials Project API key or path to a file containing the key. Only needed for fetching structures from Materials Project and if the key is not set to the “MAPI_KEY” environment variable.
- **database** (atomman.library.Database, optional) - A pre-defined Database object to use. If not given, will initialize a new Database object. Passing in a database can save time if multiple calls are made for the same record type.
- **local** (bool, optional) - Indicates if the Database object is to look for local records. Default is True. Ignored if database is given.
- **remote** (bool, optional) - Indicates if the Database object is to look for remote records. Default is True. Ignored if database is given.
- **refresh_cache** (bool, optional) - If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.
- **verbose** (bool, optional) - If True, info messages will be printed during operations. Default value is False.

### Request Example
```python
import atomman as am

mp_api_key = 'C:/Users/lmh1/Documents/Materials Project/API key.txt' # Or your actual API key path/value

try:
    ucell = am.load('dft_reference', 'mp-81', api_key=mp_api_key, verbose=True)
    print(ucell)
except Exception as e:
    print(f"An error occurred: {e}")
    # Specific error handling for MPRestError might be needed here
```

### Response
#### Success Response (200)
- **system** (atomman.System) - The system object generated from the crystal prototype.

#### Response Example
```json
{
  "system": "<atomman.System object at 0x...>"
}
```

### Error Handling
- **MPRestError**: Indicates an issue with the Materials Project REST API query, often due to an invalid or missing API key (e.g., status code 403).
- **ValueError**: Can occur if the input parameters are incorrect or if the requested data cannot be processed.
```

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

### Atomman W Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'W' in the Atomman library.

```APIDOC
## W
  * wrap() (atomman.System method)
```

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

### Atomman V Module

Source: https://www.ctcms.nist.gov/potentials/atomman/genindex.html

Documentation for elements starting with 'V' in the Atomman library.

```APIDOC
## V
  * vacancy() (in module atomman.defect)
  * value_unit() (in module atomman.unitconvert)
  * values_to_hexcolors() (in module atomman.plot)
  * vect_angle() (in module atomman.tools)
  * vector3to4() (in module atomman.tools.miller)
  * vector4to3() (in module atomman.tools.miller)
  * vector_conventional_to_primitive() (in module atomman.tools.miller)
  * vector_crystal_to_cartesian() (atomman.Box method)
    * (in module atomman.tools.miller)
  * vector_primitive_to_conventional() (in module atomman.tools.miller)
  * vects (atomman.Box property)
  * view (atomman.Atoms property)
  * VolterraDislocation (class in atomman.defect)
  * volume (atomman.Box property)
```

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

### Initialize Box with boundary coordinates

Source: https://www.ctcms.nist.gov/potentials/atomman/tutorial/1.1._Box_class.html

Sets the box using boundary coordinates and tilt factors. Default tilts are 0.

```python
# Use set with xlo, xhi, ylo, yhi, zlo, zhi and xy (default tilts are 0)
box.set(xlo=-1, xhi=5, ylo=-2.1, yhi=5, zlo=0.1, zhi=3.1, xy=0.5)
print(box)
print()

# Show that box definition coincides with parameters set
print('box.xlo ->', box.xlo)
print('box.xhi ->', box.xhi)
print('box.ylo ->', box.ylo)
print('box.yhi ->', box.yhi)
print('box.zlo ->', box.zlo)
print('box.zhi ->', box.zhi)
print('box.xy ->', box.xy)
print('box.xz ->', box.xz)
print('box.yz ->', box.yz)
```

```text
avect =  [ 6.000,  0.000,  0.000]
bvect =  [ 0.500,  7.100,  0.000]
cvect =  [ 0.000,  0.000,  3.000]
origin = [-1.000, -2.100,  0.100]

box.xlo -> -1.0
box.xhi -> 5.0
box.ylo -> -2.1
box.yhi -> 5.0
box.zlo -> 0.1
box.zhi -> 3.1
box.xy -> 0.5
box.xz -> 0.0
box.yz -> 0.0
```