matscipy

https://libatoms.github.io/matscipy/
Admin
matscipy is a materials science toolbox built around the Atomic Simulation Environment (ASE)...
Tokens:158,739
Snippets:1,342
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Importing necessary libraries

Source: https://libatoms.github.io/matscipy/_sources/applications/electrochemistry_1.py.txt

Initial setup for numerical calculations and plotting.

```python
import numpy as np
import scipy.constants as sc
import matplotlib.pyplot as plt
```

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

### VaspClient.start

Source: https://libatoms.github.io/matscipy/generated/matscipy.socketcalc.html

Starts an individual client process.

```APIDOC
## VaspClient.start(label=None)

### Description
Starts an individual client. Raises RuntimeError if this client is already running.
```

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

### Initialize Quasi-Static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Setup the initial configuration for a crack propagation simulation.

```python
from matscipy.models import QuasiStaticCrack

# Initialize the crack model
crack = QuasiStaticCrack(atoms=atoms, potential=potential)
crack.run(steps=100)
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Setup the initial configuration and potential for a quasi-static crack simulation.

```python
from matscipy.crack import QuasiStaticCrack

# Initialize the crack simulation
crack = QuasiStaticCrack(atoms, potential)
```

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

### Quasi-Static Crack Simulation Setup

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Initializes the simulation environment and defines the necessary parameters for crack propagation.

```python
import numpy as np
from matscipy.crack import QuasiStaticCrack

# Initialize the crack simulation
crack = QuasiStaticCrack(atoms=atoms, crack_tip=crack_tip_pos)
crack.run(steps=100)
```

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

### Define Parameter File Format

Source: https://libatoms.github.io/matscipy/_sources/topology/setup_non-reactive_simulations.ipynb.txt

Example of the expected format for a full parameter configuration file.

```text
# Element
C1 0.0028 3.50 -0.06
H1 0.0013 2.50  0.06
...

# Bonds
C1-C1 13.4 1.5
C1-H1 14.3 1.1
...

# Angles
C1-C1-H1 1.5 110.0
C1-C1-H2 1.1 115.0
...

# Dihedrals
H1-C1-C1-H2 0.0 0.0 0.016 0.0
...

# Cutoffs
C1-C1 1.85
...
```

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

### Syntax warning example

Source: https://libatoms.github.io/matscipy/applications/electrochemistry_1.html

Example of syntax warnings encountered during execution.

```text
<>:42: SyntaxWarning: invalid escape sequence '\p'
<>:42: SyntaxWarning: invalid escape sequence '\p'
/tmp/ipykernel_4184/1530268794.py:42: SyntaxWarning: invalid escape sequence '\p'
  ax1.set_ylabel('potential $\phi$ (V)')
```

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

### Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Example of setting up a quasi-static crack propagation simulation.

```python
import numpy as np
from matscipy.fracture.quasi_static import QuasiStaticCrack

# Define the crack propagation parameters
crack = QuasiStaticCrack(atoms=atoms, crack_tip=crack_tip, crack_plane=crack_plane)
crack.run(steps=100, displacement=0.01)
```

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

### serve_forever

Source: https://libatoms.github.io/matscipy/generated/matscipy.socketcalc.html

Starts the server loop to handle incoming requests.

```APIDOC
## serve_forever(poll_interval=0.5)

### Description
Handles one request at a time until the server is shut down. It polls for shutdown signals every poll_interval seconds.

### Parameters
- **poll_interval** (float) - Optional - The interval in seconds to poll for shutdown signals.
```

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

### Loading parameter files

Source: https://libatoms.github.io/matscipy/topology/setup_non-reactive_simulations.html

Example of a full parameter file structure and loading it to set atom and interaction data.

```text
# Element
C1 0.0028 3.50 -0.06
H1 0.0013 2.50  0.06
...

# Bonds
C1-C1 13.4 1.5
C1-H1 14.3 1.1
...

# Angles
C1-C1-H1 1.5 110.0
C1-C1-H2 1.1 115.0
...

# Dihedrals
H1-C1-C1-H2 0.0 0.0 0.016 0.0
...

# Cutoffs
C1-C1 1.85
...
```

```python
cutoffs, atom_data, bond_data, angle_data, dih_data = matscipy.io.opls.read_parameter_file('parameters.in')

a.set_cutoffs(cutoffs)
a.set_atom_data(atom_data)
```

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

### Defining interaction cutoffs

Source: https://libatoms.github.io/matscipy/topology/setup_non-reactive_simulations.html

Example format for a cutoff configuration file and how to load it into the structure.

```text
# Cutoffs
C1-C1 1.85
C1-H1 1.15
...
```

```python
import matscipy.io.opls

cutoffs = matscipy.io.opls.read_cutoffs('cutoffs.in')
a.set_cutoffs(cutoffs)

bond_types, _ = a.get_bonds()
print(bond_types)
```

```text
['C1-C1' 'C1-H1' 'C1-H2']
```

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

### Define Cutoff File Format

Source: https://libatoms.github.io/matscipy/_sources/topology/setup_non-reactive_simulations.ipynb.txt

Example of the expected format for a cutoff configuration file.

```text
# Cutoffs
C1-C1 1.85
C1-H1 1.15
...
```

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

### Read OPLS Parameter File

Source: https://libatoms.github.io/matscipy/generated/matscipy.io.opls.html

Example structure for a file containing non-reactive potential parameters.

```text
# Element
C1 0.001 3.5 -0.01  # name, LJ-epsilon (eV), LJ-sigma (A), charge (e)
H1 0.001 2.5  0.01  # name, LJ-epsilon (eV), LJ-sigma (A), charge (e)

# Cutoffs-LJ-Coulomb (this block is optional)
LJ 10.0  # distance (A)
C  10.0  # distance (A)

# LJ-pairs (this block is optional)
C1-H1 0.002 2.1 12.0  # name, epsilon (eV), sigma (A), cutoff (A)

# Bonds
C1-C1 10.0 1.0  # name, spring constant*2 (eV/A**2), distance (A)

# Angles
H1-C1-C1 1.0 100.0  # name, spring constant*2 (eV), equilibrium angle

# Dihedrals
H1-C1-C1-H1 0.0 0.0 0.01 0.0  # name, energy (eV), energy (eV), ...

# Cutoffs
C1-C1 1.85  # name, cutoff (A)
C1-H1 1.15  # name, cutoff (A)
```

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

### Example Output for Elastic Constants

Source: https://libatoms.github.io/matscipy/applications/cylinder_configurations.html

Sample output values for the tungsten elastic constants calculation.

```text
3.143 (Angstrom), 538.90, 219.93, 178.80 (GPa)
```

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

### Setup Crack System

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Defines the crystal structure, sets atom groups, and computes the initial crack tip position.

```python
n               = [ 4, 4, 1 ]
crack_surface   = [ 1, 1, 1 ]
crack_front     = [ 1, -1, 0 ]
crack_tip       = [ 41, 56 ]
skin_x, skin_y = 1, 1

vacuum          = 6.0
fmax            = 0.05

# Setup crack system
cryst = diamond(el, a0, n, crack_surface, crack_front)
set_groups(cryst, n, skin_x, skin_y)

ase.io.write('cryst.cfg', cryst)

# Compute crack tip position
r0 = np.sum(cryst.get_positions()[crack_tip,:], axis=0)/len(crack_tip)
tip_x0, tip_y0, tip_z0 = r0
```

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

### Initialize Beta-90 Degree Partial Dislocation

Source: https://libatoms.github.io/matscipy/_sources/applications/multispecies_dislocations.ipynb.txt

Start the construction of a beta-terminated dislocation in GaAs.

```python
GaAs = bulk("GaAs", crystalstructure="zincblende", cubic=True, a=alat)
```

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

### Initialize DihedralsData with hash

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Example dictionary structure for initializing DihedralsData with dihedral names and potential parameters.

```python
{'AA-BB-CC-DD': [1., 1., 1., 1.],
 'AA-BB-AA-BB': [2., 2., 2., 2.], ...}
```

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

### Read OPLS Cutoffs File

Source: https://libatoms.github.io/matscipy/generated/matscipy.io.opls.html

Example structure for a file containing non-reactive system cutoffs.

```text
# Cutoffs
C1-C1 1.23  # name, cutoff (A)
H1-H1 4.56  # name, cutoff (A)
C1-H1 7.89  # name, cutoff (A)
```

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

### Periodic displacement convergence output

Source: https://libatoms.github.io/matscipy/applications/quadrupole_dislocations.html

Example output showing the convergence of periodic displacements during quadrupole construction.

```text
Periodic displacement iteration 0 -> max(|dr|) = 1.0963
Periodic displacement iteration 1 -> max(|dr|) = 0.1552
Periodic displacement iteration 2 -> max(|dr|) = 0.0059
Periodic displacement iteration 3 -> max(|dr|) = 0.0015
Periodic displacement iteration 4 -> max(|dr|) = 0.0006
Periodic displacements converged to r_tol=0.001 after 4 iterations
```

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

### Define BondData parameters

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Example dictionary structure for initializing BondData with bond names and their corresponding potential parameters.

```python
{'AA-BB': [10., 1.], 'AA-CC': [20., 2.], ...}.
```

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

### Inspect and use array strides

Source: https://libatoms.github.io/matscipy/generated/matscipy.surface.html

Examples showing how to inspect array strides and calculate element offsets for multi-dimensional arrays.

```python
>>> import numpy as np
>>> y = np.reshape(np.arange(2 * 3 * 4, dtype=np.int32), (2, 3, 4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]], dtype=np.int32)
>>> y.strides
(48, 16, 4)
>>> y[1, 1, 1]
np.int32(17)
>>> offset = sum(y.strides * np.array((1, 1, 1)))
>>> offset // y.itemsize
np.int64(17)
```

```python
>>> x = np.reshape(np.arange(5*6*7*8, dtype=np.int32), (5, 6, 7, 8))
>>> x = x.transpose(2, 3, 1, 0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3, 5, 2, 2], dtype=np.int32)
>>> offset = sum(i * x.strides)
>>> x[3, 5, 2, 2]
np.int32(813)
>>> offset // x.itemsize
np.int64(813)
```

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

### Configure matscipy-quasistatic-crack

Source: https://libatoms.github.io/matscipy/_sources/cli/fracture_mechanics.md.txt

Example params.py file for defining material properties, crack geometry, and simulation steps for quasistatic K-field-controlled crack calculations.

```Python
import numpy as np

import ase.io

from matscipy.fracture_mechanics.clusters import diamond, set_groups

from atomistica import TersoffScr, Tersoff_PRB_39_5566_Si_C__Scr

###
# Interaction potential
calc = TersoffScr(**Tersoff_PRB_39_5566_Si_C__Scr)

# Fundamental material properties
el = 'C'
a0 = 3.57

# Elastic constants: either specify explicitly or compute automatically
compute_elastic_constants = True
# C11 = 1220.   # GPa
# C12 = -3.    # GPa
# C44 = 535.    # GPa

# Surface energy
surface_energy = 2.7326 * 10  # GPa*A = 0.1 J/m^2

# Crack system
crack_surface = [1, 1, 1]  # Normal of crack face
crack_front = [1, -1, 0]  # Direction of crack front
# bond = (10, 11)
bondlength = 1.7  # Bond length for crack tip detection
bulk_nn = 4  # Number of nearest neighbors in the bulk

vacuum = 6.0  # Vacuum surrounding the cracked cluster

# Simulation control
nsteps = 31
# Increase stress intensity factor
k1 = np.linspace(0.8, 1.2, nsteps)
# Don't move crack tip
tip_dx = np.zeros_like(k1)
tip_dz = np.zeros_like(k1)

fmax = 0.05  # Tolerance for quasistatic optimizer

# The actual crack system
n = [1, 1, 1]
skin_x, skin_y = 1, 1
cryst = diamond(el, a0, n, crack_surface, crack_front)
set_groups(cryst, n, skin_x, skin_y)  # Outer fixed atoms
ase.io.write('cryst.xyz', cryst, format='extxyz')  # Dump initial crack system (without notch)
```

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

### Deprecation warning example

Source: https://libatoms.github.io/matscipy/applications/tribology.html

Example of a warning message generated during simulation execution.

```text
/tmp/ipykernel_4588/2714859955.py:40: FutureWarning: Please use atoms.calc = calc
  atoms.set_calculator(calc)
```

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

### Initializing the PNP system

Source: https://libatoms.github.io/matscipy/_sources/applications/electrochemistry_1.py.txt

Create an instance of the solver with the defined parameters.

```python
pnp = PoissonNernstPlanckSystem(c=c, z=z, L=L, delta_u=delta_u)
```

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

### Define array for stride demonstration

Source: https://libatoms.github.io/matscipy/generated/matscipy.surface.html

Example of a 2D array of 32-bit integers used to explain memory layout and strides.

```python
x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)
```

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

### Creating and Manipulating Array Views

Source: https://libatoms.github.io/matscipy/generated/matscipy.surface.html

Examples of creating views on arrays, including changing data types, using recarrays, and handling memory contiguity constraints.

```python
>>> import numpy as np
>>> x = np.array([(-1, 2)], dtype=[('a', np.int8), ('b', np.int8)])
```

```python
>>> nonneg = np.dtype([("a", np.uint8), ("b", np.uint8)])
>>> y = x.view(dtype=nonneg, type=np.recarray)
>>> x["a"]
array([-1], dtype=int8)
>>> y.a
array([255], dtype=uint8)
```

```python
>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([2.,  3.])
```

```python
>>> xv[0,1] = 20
>>> x
array([(1, 20), (3,  4)], dtype=[('a', 'i1'), ('b', 'i1')])
```

```python
>>> z = x.view(np.recarray)
>>> z.a
array([1, 3], dtype=int8)
```

```python
>>> x[0] = (9, 10)
>>> z[0]
np.record((9, 10), dtype=[('a', 'i1'), ('b', 'i1')])
```

```python
>>> x = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.int16)
>>> y = x[:, ::2]
>>> y
array([[1, 3],
       [4, 6]], dtype=np.int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
    ...
ValueError: To change to a dtype of a different size, the last axis must be contiguous
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 3)],
       [(4, 6)]], dtype=[('width', '<i2'), ('length', '<i2')])
```

```python
>>> x = np.arange(2 * 3 * 4, dtype=np.int8).reshape(2, 3, 4)
>>> x.transpose(1, 0, 2).view(np.int16)
array([[[ 256,  770],
        [3340, 3854]],

       [[1284, 1798],
        [4368, 4882]],

       [[2312, 2826],
        [5396, 5910]]], dtype=int16)
```

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

### Get Dihedrals

Source: https://libatoms.github.io/matscipy/_sources/topology/setup_non-reactive_simulations.ipynb.txt

Retrieves dihedral types from the system.

```python
dih_types, _ = a.get_dihedrals()
print(dih_types)
```

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

### Configure matscipy-sinclair-crack

Source: https://libatoms.github.io/matscipy/_sources/cli/fracture_mechanics.md.txt

Example params.py file for Sinclair-style fracture simulations using the Kumagai potential, defining regions for flexible boundary conditions.

```Python
import numpy as np
from matscipy.fracture_mechanics.clusters import diamond, set_groups, set_regions
import ase.io
import atomistica

# Interaction potential
calc = atomistica.KumagaiScr()

# Fundamental material properties
el = 'Si'
a0 = 5.429
surface_energy = 1.08 * 10  # GPa*A = 0.1 J/m^2

elastic_symmetry = 'cubic'

# Crack system
crack_surface = [1, 1, 1]
crack_front = [1, -1, 0]

vacuum = 6.0

# Simulation control
ds = 0.01
nsteps = 10000
continuation = True

k0 = 0.9
dk = 1e-4

fmax = 1e-2
max_steps = 50

r_I = 15.0
cutoff = 6.0
r_III = 40.0

n = [2 * int((r_III + cutoff)/ a0), 2 * int((r_III + cutoff)/ a0) - 1, 1]
print('n=', n)

# Setup crack system and regions I, II, III and IV
cryst = diamond(el, a0, n, crack_surface, crack_front)
cluster = set_regions(cryst, r_I, cutoff, r_III)  # carve circular cluster

ase.io.write('cryst.cfg', cryst)
ase.io.write('cluster.cfg', cluster)
```

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

### Set and get array fields

Source: https://libatoms.github.io/matscipy/generated/matscipy.surface.html

Demonstrates using setfield and getfield to manipulate raw data representation within an array.

```python
>>> import numpy as np
>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[1.,  0.,  0.],
       [0.,  1.,  0.],
       [0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]], dtype=int32)
>>> x
array([[1.0e+000, 1.5e-323, 1.5e-323],
       [1.5e-323, 1.0e+000, 1.5e-323],
       [1.5e-323, 1.5e-323, 1.0e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[1.,  0.,  0.],
       [0.,  1.,  0.],
       [0.,  0.,  1.]])
```

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

### shape

Source: https://libatoms.github.io/matscipy/generated/matscipy.surface.html

A property representing the tuple of array dimensions, used to get or set the shape of an array in-place.

```APIDOC
## shape

### Description
Tuple of array dimensions. Can be used to get the current shape or reshape the array in-place by assigning a new tuple.

### Warning
Setting `arr.shape` is deprecated and may be removed in the future. Using `ndarray.reshape` is the preferred approach.
```

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

### Get Angles

Source: https://libatoms.github.io/matscipy/_sources/topology/setup_non-reactive_simulations.ipynb.txt

Retrieves angle types from the system.

```python
angle_types, _ = a.get_angles()
print(angle_types)
```

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

### Initialize Simulation Environment

Source: https://libatoms.github.io/matscipy/_sources/applications/tribology.ipynb.txt

Sets up the simulation parameters, loads the atomic structure, and assigns the Stillinger-Weber calculator.

```python
gamma_langevin = 1. / t_langevin  # derived Langevin parameter
t_integrate = 100.0 * fs  # simulation time
steps_integrate = int(t_integrate / dt)  # number of simulation steps

# get atoms from trajectory to also initialize correct velocities
atoms = read('equilibrate_pressure_02.traj')

bottom_mask = np.loadtxt("bottom_mask.txt").astype(bool)
top_mask = np.loadtxt("top_mask.txt").astype(bool)

calc = Manybody(**StillingerWeber(Stillinger_Weber_PRB_31_5262_Si))  # specify calculator
atoms.set_calculator(calc)
```

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

### Resize an array in-place

Source: https://libatoms.github.io/matscipy/generated/matscipy.surface.html

Examples of shrinking and enlarging arrays using the resize method, including handling of memory order and reference checks.

```python
>>> import numpy as np
```

```python
>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])
```

```python
>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])
```

```python
>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])
```

```python
>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that references or is referenced ...
```

```python
>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])
```

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

### Initialize and Solve PNP System

Source: https://libatoms.github.io/matscipy/_sources/applications/electrochemistry_1.py.txt

Creates the solver instance and executes the simulation with specific boundary conditions.

```python
pnp = PoissonNernstPlanckSystem(c,z,L, lambda_S=lambda_S, delta_u=delta_u, N=200, maxit=20, e=1e-6)

pnp.use_stern_layer_cell_bc()

pnp.output = True
xij = pnp.solve()
```

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

### Display Output

Source: https://libatoms.github.io/matscipy/applications/cylinder_configurations.html

Example output for cell orientation and Burgers vector.

```text
Cell orientation:
```

```text
[[ 1 -1  0]
 [ 1  1  1]
 [-1 -1  2]]
Burgers vector:
[ 1.76 -1.76  0.  ]
```

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

### init(c, z, L, lambda_S, x0, T, delta_u, relative_permittivity, vacuum_permittivity, R, F, N, e, maxit, solver, potential0, concentration0)

Source: https://libatoms.github.io/matscipy/generated/matscipy.electrochemistry.poisson_nernst_planck_solver.html

Initializes a 1D Poisson-Nernst-Planck system description using SI units.

```APIDOC
## Constructor: init

### Description
Initializes a 1D Poisson-Nernst-Planck system description. Expects quantities in SI units per default.

### Parameters
- **c** (ndarray, optional) - Bulk concentrations of each ionic species [mol/m^3].
- **z** (ndarray, optional) - Charge of each ionic species [1].
- **x0** (float, optional) - Left hand side reference position.
- **L** (float, optional) - 1D domain size [m].
- **lambda_S** (float, optional) - Stern layer thickness in case of Robin BC [m].
- **T** (float, optional) - Temperature of the solution [K].
- **delta_u** (float, optional) - Potential drop across 1D cell [V].
- **relative_permittivity** (float, optional) - Relative permittivity of the ionic solution [1].
- **vacuum_permittivity** (float, optional) - Vacuum permittivity [F m^-1].
- **R** (float, optional) - Molar gas constant [J mol^-1 K^-1].
- **F** (float, optional) - Faraday constant [C mol^-1].
- **N** (int, optional) - Number of discretization grid segments.
- **e** (float, optional) - Absolute tolerance for Newton solver convergence.
- **maxit** (int, optional) - Maximum number of Newton iterations.
- **solver** (func, optional) - Solver to use.
- **potential0** (ndarray, optional) - Potential initial values.
- **concentration0** (ndarray, optional) - Concentration initial values.
```

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

### Representing Dihedral Lists

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Example of the dihedral list structure for a benzene molecule.

```python
[[0, 0, 1, 2, 3], [0, 1, 2, 3, 4], ... , [1, 6, 0, 1, 2],
 [1, 7, 1, 2, 3], ... , [2, 6, 0, 1, 7], [2, 7, 1, 2, 8], ...]
```

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

### Representing Dihedral Types

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Example of the dihedral type array structure for a benzene molecule.

```python
['C-C-C-C', 'C-C-C-H', 'H-C-C-H']
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration for a quasi-static crack simulation.

```python
from matscipy.crack import QuasiStaticCrack

crack = QuasiStaticCrack(atoms, crack_tip_position, crack_plane_normal, crack_front_direction)
```

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

### QMFlaggingTool.__init__

Source: https://libatoms.github.io/matscipy/generated/matscipy.calculators.mcfm.qm_cluster_tools.qm_flagging_tool.html

Initializes the QMFlaggingTool instance with parameters for cluster management and energy thresholds.

```APIDOC
## QMFlaggingTool.__init__(mediator=None, qm_flag_potential_energies=None, small_cluster_hops=3, only_heavy=False, ema_parameter=0.1, energy_cap=None, energy_increase=1)

### Description
Initializes the tool responsible for flagging atoms that move out of their equilibrium positions.

### Parameters
- **mediator** (matscipy.calculators.mcfm.QMCluster) - Optional - Class responsible for managing the QM clusters.
- **qm_flag_potential_energies** (np.array) - Optional - Thresholds for flagging individual atoms (nAtoms, 2).
- **small_cluster_hops** (int) - Optional - Number of neighbour hops to define a cluster.
- **only_heavy** (bool) - Optional - If True, only consider non-hydrogen atoms in cluster expansion.
- **ema_parameter** (float) - Optional - Parameter lambda in the exponential mean average calculation.
- **energy_cap** (float) - Optional - Cap potential energy per atom at this value.
- **energy_increase** (int) - Optional - Multiplier for potential energy per atom.
```

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

### Dihedral list output

Source: https://libatoms.github.io/matscipy/topology/setup_non-reactive_simulations.html

Example output showing the structure of a calculated dihedral list.

```python
(['H1-C1-C1-H2'],
 [[0, np.int32(2), np.int32(0), np.int32(1), np.int32(6)],
  [0, np.int32(2), np.int32(0), np.int32(1), np.int32(7)],
  [0, np.int32(2), np.int32(0), np.int32(1), np.int32(5)],
  [0, np.int32(4), np.int32(0), np.int32(1), np.int32(6)],
  [0, np.int32(4), np.int32(0), np.int32(1), np.int32(7)],
  [0, np.int32(4), np.int32(0), np.int32(1), np.int32(5)],
  [0, np.int32(3), np.int32(0), np.int32(1), np.int32(6)],
  [0, np.int32(3), np.int32(0), np.int32(1), np.int32(7)],
  [0, np.int32(3), np.int32(0), np.int32(1), np.int32(5)],
  [0, np.int32(10), np.int32(8), np.int32(9), np.int32(14)],
  [0, np.int32(10), np.int32(8), np.int32(9), np.int32(15)],
  [0, np.int32(10), np.int32(8), np.int32(9), np.int32(13)],
  [0, np.int32(12), np.int32(8), np.int32(9), np.int32(14)],
  [0, np.int32(12), np.int32(8), np.int32(9), np.int32(15)],
  [0, np.int32(12), np.int32(8), np.int32(9), np.int32(13)],
  [0, np.int32(11), np.int32(8), np.int32(9), np.int32(14)],
  [0, np.int32(11), np.int32(8), np.int32(9), np.int32(15)],
  [0, np.int32(11), np.int32(8), np.int32(9), np.int32(13)]])
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration and potential energy calculator for a crack propagation simulation.

```python
from matscipy.calculators import EMT
from ase.build import bulk
from ase.constraints import FixAtoms
from ase.optimize import FIRE

atoms = bulk('Cu', cubic=True) * (10, 10, 1)
atoms.calc = EMT()

# Fix the bottom layer
constraint = FixAtoms(mask=[atom.tag > 2 for atom in atoms])
atoms.set_constraint(constraint)

# Minimize energy
opt = FIRE(atoms)
opt.run(fmax=0.05)
```

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

### Read LAMMPS Definitions

Source: https://libatoms.github.io/matscipy/generated/matscipy.io.opls.html

Example of a LAMMPS parameter file and the resulting dictionary mapping.

```text
bond_style      harmonic
bond_coeff      1 1.2 3.4 # AA-AA
bond_coeff      2 5.6 7.8 # AA-BB
```

```text
bond_type_index[0] = 'AA-AA'
bond_type_index[1] = 'AA-BB'
```

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

### Initialize PNP Solver

Source: https://libatoms.github.io/matscipy/applications/electrochemistry_1.html

Instantiate the PoissonNernstPlanckSystem with the defined parameters.

```python
pnp = PoissonNernstPlanckSystem(c,z,L, lambda_S=lambda_S, delta_u=delta_u, N=200, maxit=20, e=1e-6)
```

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

### rotate_dihedral

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Rotates a group of atoms by a predefined dihedral angle, starting from its current configuration.

```APIDOC
## rotate_dihedral(a1, a2, a3, a4, angle, mask=None, indices=None)

### Description
Rotate a group of atoms by a predefined dihedral angle, starting from its current configuration.

### Parameters
- **a1, a2, a3, a4** (int) - Required - Indices of the four atoms defining the dihedral angle.
- **angle** (float) - Required - The angle in degrees to rotate.
- **mask** (list, optional) - Optional - A mask defining the subgroup of atoms to move.
- **indices** (list, optional) - Optional - Explicit indices of the atoms to be rotated.
```

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

### Initialize Quasi-Static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration for a crack propagation simulation.

```python
from matscipy.crack import QuasiStaticCrack

# Initialize the crack simulation object
crack = QuasiStaticCrack(atoms, crack_tip_position, crack_plane_normal)
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration for a crack propagation simulation.

```python
from matscipy.models import QuasiStaticCrack

crack = QuasiStaticCrack(atoms=atoms, potential=potential)
crack.initialize()
```

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

### Initialize Quasi-Static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration for a crack propagation simulation.

```python
from matscipy.crack import QuasiStaticCrack

# Initialize the crack simulation
crack = QuasiStaticCrack(atoms, crack_tip_position, crack_plane_normal)
```

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

### main

Source: https://libatoms.github.io/matscipy/_sources/generated/matscipy.cli.electrochemistry.poisson_nernst_planck_solver.rst.txt

The main entry point function for the Poisson-Nernst-Planck solver CLI.

```APIDOC
## main

### Description
Executes the main logic for the Poisson-Nernst-Planck solver command-line interface.

### Signature
`matscipy.cli.electrochemistry.poisson_nernst_planck_solver.main()`
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial state for a quasi-static crack propagation simulation.

```python
from matscipy.models import QuasiStaticCrack

# Initialize the crack model
crack = QuasiStaticCrack(atoms=atoms, potential=potential)
crack.run()
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial atomic configuration and boundary conditions for a crack propagation simulation.

```python
from matscipy.crack import QuasiStaticCrack

# Initialize the crack simulation object
crack = QuasiStaticCrack(atoms=atoms, crack_tip_position=[0, 0, 0])
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration for a crack propagation simulation, including defining the crack tip and boundary conditions.

```python
import numpy as np
from matscipy.crack import QuasiStaticCrack

# Define the crack tip position and simulation parameters
crack_tip = np.array([0.0, 0.0, 0.0])
crack = QuasiStaticCrack(atoms, crack_tip=crack_tip, force_threshold=0.05)
```

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

### Read Cutoffs and Get Bonds

Source: https://libatoms.github.io/matscipy/_sources/topology/setup_non-reactive_simulations.ipynb.txt

Reads interaction cutoffs from a file and retrieves bond types.

```python
import matscipy.io.opls

cutoffs = matscipy.io.opls.read_cutoffs('cutoffs.in')
a.set_cutoffs(cutoffs)

bond_types, _ = a.get_bonds()
print(bond_types)
```

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

### Initialize Quasi-static Crack Simulation

Source: https://libatoms.github.io/matscipy/_sources/applications/quasi_static_crack.ipynb.txt

Sets up the initial configuration for a crack propagation simulation, including defining the crack tip and boundary conditions.

```python
import numpy as np
from matscipy.crack import QuasiStaticCrack

# Define the crack tip position and simulation parameters
crack_tip = np.array([0.0, 0.0, 0.0])
crack = QuasiStaticCrack(atoms, crack_tip=crack_tip, crack_plane=[0, 1, 0])
```

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

### Retrieve angle list for particle interactions

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Example output for ang_list and ang_types for a system with 7 atoms.

```python
['A1-A1-A1', 'A2-A1-A2']
```

```python
[[0, 0, 1, 2], [1, 0, 3, 4], [1, 0, 5, 6]]
```

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

### Initialize MD simulation parameters and calculator

Source: https://libatoms.github.io/matscipy/applications/tribology.html

Sets up physical constants, simulation parameters, and the Stillinger-Weber calculator for the system.

```python
from ase.units import GPa, fs, m, s
from ase.io import read
import numpy as np
from matscipy.calculators.manybody.explicit_forms.stillinger_weber import StillingerWeber, Stillinger_Weber_PRB_31_5262_Si
from matscipy.calculators.manybody import Manybody

dt = 5.0 * fs  # MD time step
C11 = 166.0 * GPa  # material constant
p_c = 0.20  # empirical cutoff parameter value to remove high-frequency oscillations of the system 

Pdir = 2  # index of cell axis along normal pressure is applied
P = 1.0 * GPa  # target normal pressure
v = 100.0 * m / s  # constant sliding speed
vdir = 0  # index of cell axis along sliding happens
T = 300.0  # target temperature for thermostat

t_langevin = 75.0 * fs  # time constant for Langevin thermostat
gamma_langevin = 1. / t_langevin  # derived Langevin parameter
t_integrate = 100.0 * fs  # simulation time
steps_integrate = int(t_integrate / dt)  # number of simulation steps

# get atoms from trajectory to also initialize correct velocities
atoms = read('equilibrate_pressure_02.traj')

bottom_mask = np.loadtxt("bottom_mask.txt").astype(bool)
top_mask = np.loadtxt("top_mask.txt").astype(bool)

calc = Manybody(**StillingerWeber(Stillinger_Weber_PRB_31_5262_Si))  # specify calculator
atoms.set_calculator(calc)
```

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

### Configure MD simulation parameters

Source: https://libatoms.github.io/matscipy/_sources/applications/tribology.ipynb.txt

Sets up physical constants, time steps, and thermostat parameters for the pressure equilibration simulation.

```python
from ase.units import GPa, fs

dt = 5.0 * fs  # MD time step
C11 = 166.0 * GPa  # material constant
M_factor = 1.0  # scaling factor for lid mass during equilibration,
# 1.0 will give fast equilibration for expensive calculators

Pdir = 2  # index of cell axis along which the normal pressure is applied
P = 1.0 * GPa  # target normal pressure
v = 0.0  # no sliding yet, only apply pressure
vdir = 0  # index of cell axis along which sliding happens
T = 300.0  # target temperature for thermostat in K

t_langevin = 75.0 * fs  # time constant for Langevin thermostat
gamma_langevin = 1. / t_langevin  # derived Langevin parameter
t_integrate = 100.0 * fs  # simulation time
steps_integrate = int(t_integrate / dt)  # number of simulation steps
```

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

### main

Source: https://libatoms.github.io/matscipy/_sources/generated/matscipy.cli.glasses.quench.rst.txt

The main entry point for the quenching CLI command.

```APIDOC
## main

### Description
Executes the primary logic for the quenching command-line interface.
```

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

### Initialize AnglesData with hash

Source: https://libatoms.github.io/matscipy/generated/matscipy.opls.html

Example dictionary structure for initializing AnglesData with angle names and potential parameters.

```python
{'AA-BB-CC': [10., 1.], 'AA-CC-BB': [20., 2.], ...}
```

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

### Extended XYZ file format

Source: https://libatoms.github.io/matscipy/topology/setup_non-reactive_simulations.html

Example of an extended XYZ file structure used for non-reactive simulations.

```text
42
Lattice="10.0 0.0 0.0 0.0 10.0 0.0 0.0 0.0 10.0" Properties=species:S:1:pos:R:3:molid:I:1:type:S:1 pbc="F F F"
C        4.5       6.5       5.0       1        C1
H        4.5       5.5       5.0       1        H1
H        5.5       3.5       4.0       2        H2
...
```

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

### QMClusteringTool.__init__

Source: https://libatoms.github.io/matscipy/generated/matscipy.calculators.mcfm.qm_cluster_tools.qm_clustering_tool.html

Initializes the QMClusteringTool with a mediator and a list of doubly bonded atoms.

```APIDOC
## QMClusteringTool(mediator=None, double_bonded_atoms_list=[])

### Description
Initializes the tool responsible for managing QM cluster carving and hydrogenation.

### Parameters
- **mediator** (matscipy.calculators.mcfm.QMCluster) - Optional - Class responsible for managing the QM clusters in the simulation.
- **double_bonded_atoms_list** (list) - Optional - List of doubly bonded atoms, needed for double hydrogenation.
```

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

### Dihedral calculation data structure

Source: https://libatoms.github.io/matscipy/topology/setup_non-reactive_simulations.html

Example of the data structure returned for dihedral calculations in a molecular system.

```python
(['C1-C1-H1', 'H1-C1-H1', 'C1-C1-H2', 'H2-C1-H2'],
 [[0, np.int32(2), 0, np.int32(1)],
  [1, np.int32(2), 0, np.int32(4)],
  [0, np.int32(1), 0, np.int32(4)],
  [1, np.int32(2), 0, np.int32(3)],
  [0, np.int32(1), 0, np.int32(3)],
  [1, np.int32(4), 0, np.int32(3)],
  [2, np.int32(0), 1, np.int32(6)],
  [2, np.int32(0), 1, np.int32(7)],
  [3, np.int32(6), 1, np.int32(7)],
  [2, np.int32(0), 1, np.int32(5)],
  [3, np.int32(6), 1, np.int32(5)],
  [3, np.int32(7), 1, np.int32(5)],
  [0, np.int32(10), 8, np.int32(9)],
  [1, np.int32(10), 8, np.int32(12)],
  [0, np.int32(9), 8, np.int32(12)],
  [1, np.int32(10), 8, np.int32(11)],
  [0, np.int32(9), 8, np.int32(11)],
  [1, np.int32(12), 8, np.int32(11)],
  [2, np.int32(8), 9, np.int32(14)],
  [2, np.int32(8), 9, np.int32(15)],
  [3, np.int32(14), 9, np.int32(15)],
  [2, np.int32(8), 9, np.int32(13)],
  [3, np.int32(14), 9, np.int32(13)],
  [3, np.int32(15), 9, np.int32(13)]])
```

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

### Initialize system and constraints for pressure equilibration

Source: https://libatoms.github.io/matscipy/applications/tribology.html

Reads the previous trajectory and constraint masks to set up the system state and pressure coupling constraints.

```python
from ase.units import GPa, fs
from matscipy.calculators.manybody.explicit_forms.stillinger_weber import StillingerWeber, Stillinger_Weber_PRB_31_5262_Si
from matscipy.calculators.manybody import Manybody
from matscipy import pressurecoupling as pc
from ase.io import read
import numpy as np

dt = 5.0 * fs  # MD time step
C11 = 166.0 * GPa  # material constant
M_factor = 1.0  # scaling factor for lid mass during equilibration

Pdir = 2  # index of cell axis along normal pressure is applied
P = 1.0 * GPa  # target normal pressure
v = 0.0  # no sliding yet, only apply pressure
vdir = 0  # index of cell axis along sliding happens
T = 300.0  # target temperature for the thermostat

t_langevin = 75.0 * fs  # time constant for Langevin thermostat
gamma_langevin = 1. / t_langevin  # derived Langevin parameter
t_integrate = 100.0 * fs  # simulation time
steps_integrate = int(t_integrate / dt)  # number of simulation steps

# get atoms from trajectory to also initialize correct velocities
atoms = read('equilibrate_pressure_01.traj')

bottom_mask = np.loadtxt("bottom_mask.txt").astype(bool)
top_mask = np.loadtxt("top_mask.txt").astype(bool)

damp = pc.FixedMassCriticalDamping(C11, M_factor)
slider = pc.SlideWithNormalPressureCuboidCell(top_mask, bottom_mask,
                                              Pdir, P, vdir, v, damp)
atoms.set_constraint(slider)

calc = Manybody(**StillingerWeber(Stillinger_Weber_PRB_31_5262_Si))  # specify calculator
atoms.set_calculator(calc)
```
Tokens:
Raw