Mat3ra API Examples

Contents of this Repository

API Examples (examples/)

Notebooks demonstrating the Mat3ra REST API, in roughly the order a new user should follow.

Folder	Notebook	Description
system	Get Authentication Params	Programmatically find your user ID and access token.
material	Get Materials by Formula	Query materials stored on your account by chemical formula.
material	Create Material	Generate a material in JSON format and upload it to your account.
material	Import Materials from POSCAR	Import materials directly from POSCAR files.
workflow	Get Workflows	Query the API to search for workflows by type.
workflow	Quantum Espresso Workflow and Job	Create a QE workflow from an input file, submit a job, and post-process results.
job	Create and Submit Job	Create and run a DFT job via the API.
job	Get File from Job	Query job output files and download them to disk.
job	Run Simulations and Extract Properties	Copy a bank workflow and calculate band gaps for multiple materials.
job	ML — Train Model and Predict Properties	Generate a training dataset, train an ML model, and predict band gaps.
reproducing_publications	Band Gaps — Twisted MoS₂	Reproduce band gap results for bilayer twisted MoS₂ interfaces.
reproducing_publications	Band Structure — Twisted MoS₂	Reproduce band structure results for bilayer twisted MoS₂ interfaces.

Materials Designer Notebooks (other/materials_designer/)

Notebooks run inside the Materials Designer tool to create and transform material structures.

Notebook	Description
Introduction	Overview of the Materials Designer notebook environment.
Create Slab	Generate surface slab models.
Create Supercell	Build supercells from a unit cell.
Create Interface (ZSL)	Interface with minimum strain via the ZSL algorithm.
Create Interface (no strain)	Interface without strain matching.
Create Interface (ASE/EMT relaxation)	Interface with ASE/EMT relaxation.
Create Heterostructure	Assemble a van-der-Waals heterostructure.
Create Twisted Interface	Twisted interface using commensurate lattices.
Create Twisted Interface (nanoribbons)	Twisted interface from nanoribbon building blocks.
Create Grain Boundary (crystal)	Grain boundary in a bulk crystal.
Create Grain Boundary (film)	Grain boundary in a thin film.
Create Nanoribbon	Generate a nanoribbon structure.
Create Nanowire	Generate a nanowire structure.
Create Nanowire (custom shape)	Nanowire with a user-defined cross-section.
Create Monolayer	Extract a monolayer from a layered material.
Create Cluster	Create a nanoparticle cluster with a predefined shape.
Create Point Defect	Introduce a vacancy or substitution point defect.
Create Point Defect Pair	Introduce a pair of point defects.
Create Adatom Defect	Place an adatom on a surface.
Create Island Defect	Create a surface island defect.
Create Terrace Defect	Create a surface terrace defect.
Create Maxwell Disorder	Introduce Maxwell disorder into a structure.
Create Perturbation	Apply atomic perturbations.
Create Cutout	Cut out a box-shaped region from a structure.
Optimize Film Position	Optimize the vertical position of a film on a substrate.
Passivate Slab	Add passivation atoms to slab surfaces.
Passivate Edge	Passivate nanoribbon or nanowire edges.
Import from Files	Import structures from local files (CIF, POSCAR, …).
Import from JARVIS DB	Import a structure from the JARVIS database.
Import from Standata	Import structures from the Standata library.
Custom Transformation	Apply a user-defined transformation to a structure.
Under the Hood	Internals: how Materials Designer notebooks communicate with the platform.

Simulation Workflows (other/materials_designer/workflows/)

Workflow notebooks that run simulations.

Notebook	Description
Introduction	Overview of the workflow notebook environment.
Total Energy	Calculate the total DFT energy of a material.
Total Energy Convergence	Converge total energy with respect to k-points and cutoff.
Total Energy Post-Processing	Post-process total energy results.
Relaxation	Relax atomic positions and/or cell parameters.
Equation of State	Compute the equation of state (energy vs. volume).
Band Gap	Calculate the electronic band gap.
Band Structure	Compute and plot the electronic band structure.
Band Structure (HSE)	Band structure with the HSE hybrid functional.
Convergence	General convergence study.
Surface Energy	Calculate surface formation energy.
Valence Band Offset	Determine the valence band offset at an interface.

notebooks_utils — Python Utility Package

src/py/mat3ra/notebooks_utils is the shared Python library used by all notebooks. It is organised in four layers:

primitive/  →  core/  →  ipython/  →  pyodide/

Layer	Location	Purpose
primitive	notebooks_utils/primitive/	Pure stdlib: enums, environment detection, logger, CLI helpers. No third-party dependencies.
core	notebooks_utils/core/	Third-party packages (mat3ra.api_client, requests, numpy, …). No IPython or browser APIs. Organised by domain under core/entity/<domain>/ with separate api.py, io.py, and analysis.py files.
ipython	notebooks_utils/ipython/	IPython/ipywidgets display helpers, HTML/JS output, and domain-specific plots. Works in JupyterLab, Colab, and VS Code notebooks.
pyodide	notebooks_utils/pyodide/	JupyterLite-specific overrides: micropip installation, pyfetch HTTP, BroadcastChannel data bridge, and WASM/Emscripten APIs.

Top-level files (auth.py, io.py, ui.py, plot.py, settings.py, material.py, job.py) are thin routing adapters that keep notebook code environment-agnostic.

See src/py/mat3ra/notebooks_utils/README.md for the full developer guide.

Setup

NOTE: this package targets Python 3.10 or newer (requires-python in pyproject.toml). Use pyenv to manage Python versions.

Follow the steps below in order to setup and view the Jupyter notebooks:

0. Install git-lfs [3] in order to get access to the source code and notebook files.

1. Clone repository:

   git clone https://github.com/Exabyte-io/api-examples.git

   Or, if you have set up SSH keys

   git clone git@github.com:Exabyte-io/api-examples.git

   In case for some reason git-lfs was not installed at the time of cloning, the files can be pulled after installing git-lfs, through git lfs pull.

   Related to this, please be aware that as the .ipynb and .poscar files are stored on git-lfs, they are not part of the zip archive downloaded through GitHub's web interface.

2. Create a virtual environment and activate it:

   cd api-examples
   python -m venv .venv
   source .venv/bin/activate

3. Install the package with the extras that match what you want to run:

   Use case	Install command
   API examples (examples/)	pip install -e ".[api,jupyterlab]"
   Materials Designer notebooks (other/materials_designer/)	pip install -e ".[materials,jupyterlab]"
   Workflow notebooks (other/materials_designer/workflows/)	pip install -e ".[workflows,jupyterlab]"
   Everything	pip install -e ".[all,jupyterlab]"
   Development (linting, tests)	pip install -e ".[all_dev,jupyterlab]"

4. Run Jupyter and open a notebook in a browser. In order for the post-save hook feature to work properly, one must launch their Jupyter Notebook environment in the folder that contains the file config.py, which is the examples folder shown below:

   cd examples
   jupyter lab --config=config.py

Usage

In order to run or edit the examples:

1. Assert an existing Mat3ra.com account. Examples require an account to run. New users can register here to obtain one.

2. Open settings and adjust it to provide the API authentication parameters. See the corresponding example to learn how to obtain the authentication parameters. It is also possible to generate an API token by logging in to Mat3ra platform, navigating to the Account Preferences, and clicking the 'Generate new token' button under API Tokens. More details can be found here.

3. Open the desired example notebook, adjust it as necessary and run. One can speed up the notebooks execution after running the Get Authentication Params one by reusing the kernel from the first notebook.

NOTE: The Materials Project API key should be obtained from https://legacy.materialsproject.org/open.

Contribute

This is an open-source repository and we welcome contributions for other use cases. The original set of examples is only meant to demonstrate the capabilities and can be extended.

We suggest forking this repository and introducing the adjustments there. The changes in the fork can further be considered for merging into this repository as it is commonly used on GitHub. This process is explained in more details elsewhere online [4].

If you would like to add new examples or adjust existing ones, please consider the following:

1. Put examples into the corresponding directories by domain.

2. Walk the readers through the examples by providing step-by-step explanation similar to this example.

3. We use post-save hooks to automatically convert notebooks to python scripts. See config file for more information. In order to facilitate code review, we exclude notebook sources in the other/ directory from version control and store them in Git LFS [3]. Please follow this convention.

4. Apply code formatting by installing development requirements as follows:

   pip install -e ."[dev]"
   pre-commit install
   pre-commit run --all-files

   Check more details about pre-commit here.

Development

To run NBs locally with JupyterLite use https://github.com/Exabyte-io/jupyterlite repo to build and run the server.

For local API development with WebApp set the variables in the first cell of the notebooks as follows:

API_HOST = "localhost"
API_PORT = "3000"
API_SECURE = "false"
API_VERSION = "2018-10-01"

Links

1. Mat3ra.com RESTful API, description in the online documentation: link
2. Jupyter.org, official website: link
3. Git Large File Storage, official website: link
4. GitHub Standard Fork & Pull Request Workflow, online explanation: link