|Tests| |Wheels| |JOSS|
Matscipy is a generic materials science toolbox built around the Atomic Simulation Environment (ASE) <https://wiki.fysik.dtu.dk/ase/>__. It provides
useful routines for:
In addition to domain-specific routines, it also implements a set of general-purpose, low-level utilities:
Matscipy can be installed on Windows, Linux and x86 macos with::
python3 -m pip install matscipy
To get the latest version directly (requires a working compiler)::
python3 -m pip install git+https://github.com/libAtoms/matscipy.git
Compiled up-to-date wheels for Windows, Linux and x86 macos can be found here <https://github.com/libAtoms/matscipy/actions/workflows/build-wheels.yml>__.
Sphinx <http://sphinx-doc.org/>-generated documentation for the project can
be found here <http://libatoms.github.io/matscipy/>. Since Matscipy is built
on top of ASE's Atoms <https://wiki.fysik.dtu.dk/ase/ase/atoms.html#module-ase.atoms> and
Calculator <https://wiki.fysik.dtu.dk/ase/ase/calculators/calculators.html>
objects, ASE's documentation is a good complement to Matscipy's.
Issues <https://github.com/libAtoms/matscipy/issues>__ can be used to ask
questions about Matscipy.
Contributions, in the form of bug reports, improvement suggestions, documentation or pull requests, are welcome.
Running tests
To run the tests locally, from Matscipy's root directory::
python3 -m pip install .[test] # installs matscipy + test dependencies
cd tests/
python3 -m pytest .
Editable installsWhen developing matscipy, it can be useful to have an editable install of
the source directory. This means that changes to the source code are directly
reflected in the matscipy install. We are using Meson and meson-python as a
build system, and there are some restriction to editable installs <https://meson-python.readthedocs.io/en/latest/how-to-guides/editable-installs.html>__.
The editable install only works with the
--no-build-isolation option::
python3 -m pip install --no-build-isolation --editable .[test]
If you get the message::
ERROR: Tried to form an absolute path to a dir in the source tree.
then you are most likely try to install into a Python virtual environment that is located inside your source directory. This is not possible; your virtual environment needs to be located outside of the source directory.
The package requires:
Optional packages:
Please cite the following publication if you use matscipy::
@article{Grigorev2024, author = {Grigorev, Petr and Frérot, Lucas and Birks, Fraser and Gola, Adrien and Golebiowski, Jacek and Grießer, Jan and Hörmann, Johannes L. and Klemenz, Andreas and Moras, Gianpietro and Nöhring, Wolfram G. and Oldenstaedt, Jonas A. and Patel, Punit and Reichenbach, Thomas and Rocke, Thomas and Shenoy, Lakshmi and Walter, Michael and Wengert, Simon and Zhang, Lei and Kermode, James R. and Pastewka, Lars}, doi = {10.21105/joss.05668}, journal = {Journal of Open Source Software}, month = jan, number = {93}, pages = {5668}, title = {{matscipy: materials science at the atomic scale with Python}}, url = {https://joss.theoj.org/papers/10.21105/joss.05668}, volume = {9}, year = {2024} }
matscipy was partially funded by the Deutsch Forschungsgemeinschaft (project 258153560 <https://gepris.dfg.de/gepris/projekt/258153560>) and by the Engineering and Physical Sciences Research Council (grants EP/P002188/1 <https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/P002188/1>, EP/R012474/1 <https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/R012474/1> and EP/R043612/1 <https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/R043612/1>).
.. |Tests| image:: https://github.com/libAtoms/matscipy/actions/workflows/tests.yml/badge.svg :target: https://github.com/libAtoms/matscipy/actions/workflows/tests.yml
.. |Wheels| image:: https://github.com/libAtoms/matscipy/actions/workflows/wheels.yml/badge.svg :target: https://github.com/libAtoms/matscipy/actions/workflows/wheels.yml
.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.05668/status.svg :target: https://doi.org/10.21105/joss.05668