Matscipy

1.2.0 · active · verified Thu Apr 16

Matscipy is a collection of generic Python tools for materials science, building upon popular scientific computing libraries like NumPy, SciPy, and especially ASE (Atomic Simulation Environment). It provides modules for elasticity, surface generation, structure manipulation, and I/O operations for materials data. The current version is 1.2.0, and the project maintains an active development pace with multiple releases per year.

Common errors

```
ModuleNotFoundError: No module named 'matscipy.some_submodule'
```
cause Attempting to import a submodule or class that does not exist or has been moved/renamed in the current Matscipy version.

fix Consult the official Matscipy API documentation (matscipy.org/api) to verify the correct module path and class name for the functionality you intend to use.
```
TypeError: expected an Atoms object, got <class 'list'> (or similar)
```
cause A Matscipy function that expects an `ase.Atoms` object was provided with a different data type (e.g., a Python list, NumPy array, or dictionary).

fix Ensure that the input to the Matscipy function is a valid `ase.Atoms` instance. If you have raw coordinates, construct an `ase.Atoms` object using `ase.Atoms(positions=..., symbols=...)` or `ase.build` functions.
```
ImportError: You need to install 'nglview' to use the interactive viewer.
```
cause The `matscipy.structure.view()` function was called in a Jupyter environment without the `nglview` library installed, which is required for interactive visualization.

fix Install `nglview` using `pip install nglview` and enable it for your Jupyter environment if necessary (e.g., `jupyter nbextension enable --py --sys-prefix nglview`). Alternatively, use `ase gui` for standalone viewing.

Warnings

gotcha Matscipy heavily relies on the Atomic Simulation Environment (ASE) for handling atomistic structures. Users should be familiar with `ase.Atoms` objects and their methods, as many Matscipy functions expect or return these objects.
Fix: Refer to the ASE documentation (`wiki.fysik.dtu.dk/ase`) for understanding `ase.Atoms` objects and their manipulation.
gotcha Some visualization functions, such as `matscipy.structure.view`, require optional dependencies (e.g., `nglview` for interactive Jupyter notebooks or `ase gui` for a standalone viewer). Without these, the functions may raise an `ImportError` or fail silently.
Fix: Install the necessary visualization backend, e.g., `pip install nglview` for Jupyter interactive viewing.
gotcha While Matscipy strives for API stability, subtle behavior changes might occur due to updates in its core dependency, ASE. Ensure that your ASE version is compatible with the Matscipy version you are using, especially when upgrading.
Fix: Regularly check Matscipy's release notes and documentation for recommended or tested ASE versions. If encountering unexpected behavior, try updating or pinning ASE to a known compatible version.

Install

pip install matscipy Install Matscipy

Imports

fcc111
```
from matscipy.surface import fcc111
```

get_elastic_constants

from matscipy.elastic import get_elastic_constants

view
```
from matscipy.structure import view
```
Requires optional visualization dependencies.
read_structure
```
from matscipy.io import read_structure
```

Quickstart

This quickstart demonstrates how to create a simple crystal surface using `matscipy.surface.fcc111`. The generated `slab` object is an `ase.Atoms` object, which is the standard data structure used throughout Matscipy and ASE for representing atomic systems.

from matscipy.surface import fcc111
from matscipy.structure import view # Optional for visualization

# Create an Aluminum (111) slab using matscipy's surface module
slab = fcc111('Al', size=(2,2,3), vacuum=10.0, a=4.05)

print(f"Created an Al(111) slab with {len(slab)} atoms.")
print(f"Cell dimensions: {slab.get_cell()}")

# The 'slab' object is an ase.Atoms object, compatible with ASE and other matscipy functions.
# To view the structure interactively (requires optional 'nglview' or 'ase gui' installation):
# view(slab)

view raw JSON →