{"id":7396,"library":"matscipy","title":"Matscipy","description":"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.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/matscipy/matscipy","tags":["materials science","physics","simulation","scientific computing","ase","crystallography"],"install":[{"cmd":"pip install matscipy","lang":"bash","label":"Install Matscipy"}],"dependencies":[{"reason":"Fundamental numerical computing","package":"numpy"},{"reason":"Scientific computing tools","package":"scipy"},{"reason":"Plotting and visualization","package":"matplotlib"},{"reason":"Atomic Simulation Environment, core for atomistic structures","package":"ase"},{"reason":"HDF5 file format support, common for large datasets","package":"h5py"},{"reason":"Progress bars for iterations","package":"tqdm"}],"imports":[{"symbol":"fcc111","correct":"from matscipy.surface import fcc111"},{"symbol":"get_elastic_constants","correct":"from matscipy.elastic import get_elastic_constants"},{"note":"Requires optional visualization dependencies.","symbol":"view","correct":"from matscipy.structure import view"},{"symbol":"read_structure","correct":"from matscipy.io import read_structure"}],"quickstart":{"code":"from matscipy.surface import fcc111\nfrom matscipy.structure import view # Optional for visualization\n\n# Create an Aluminum (111) slab using matscipy's surface module\nslab = fcc111('Al', size=(2,2,3), vacuum=10.0, a=4.05)\n\nprint(f\"Created an Al(111) slab with {len(slab)} atoms.\")\nprint(f\"Cell dimensions: {slab.get_cell()}\")\n\n# The 'slab' object is an ase.Atoms object, compatible with ASE and other matscipy functions.\n# To view the structure interactively (requires optional 'nglview' or 'ase gui' installation):\n# view(slab)","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the ASE documentation (`wiki.fysik.dtu.dk/ase`) for understanding `ase.Atoms` objects and their manipulation.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the necessary visualization backend, e.g., `pip install nglview` for Jupyter interactive viewing.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import a submodule or class that does not exist or has been moved/renamed in the current Matscipy version.","error":"ModuleNotFoundError: No module named 'matscipy.some_submodule'"},{"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.","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).","error":"TypeError: expected an Atoms object, got <class 'list'> (or similar)"},{"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.","cause":"The `matscipy.structure.view()` function was called in a Jupyter environment without the `nglview` library installed, which is required for interactive visualization.","error":"ImportError: You need to install 'nglview' to use the interactive viewer."}]}