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	Authenticate via OIDC and inspect account credentials.
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.
Interfacial Energy	Calculate interfacial energy γ at a heterostructure.
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:

Install git-lfs [3] in order to get access to the source code and notebook files.
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.

Create a virtual environment and activate it:

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

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]"`

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:

Assert an existing Mat3ra.com account. Examples require an account to run. New users can register here to obtain one.
Open the desired example notebook and run all cells. Authentication uses OIDC device flow via await authenticate() — a browser popup opens for login. On JupyterLite (platform-embedded notebooks), credentials are injected automatically.
Optionally, for local Jupyter without OIDC, set legacy API token values in settings.json. See Get Authentication Params for details. API tokens can also be generated in Account Preferences on the platform.

NOTE: The Materials Project API key should be set in settings.json and obtained from https://next-gen.materialsproject.org/api.

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:

Put examples into the corresponding directories by domain.
Walk the readers through the examples by providing step-by-step explanation similar to this example.
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.
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"

Release files for mat3ra-notebooks-utils 2026.9.18.post0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mat3ra-notebooks-utils 2026.9.18.post0
File	Size	Uploaded
mat3ra_notebooks_utils-2026.9.18.post0.tar.gz	95.3 kB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mat3ra-notebooks-utils 2026.9.18.post0
File	Interpreter	ABI	Platform	Reset
mat3ra_notebooks_utils-2026.9.18.post0-py3-none-any.whl 92.4 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 187.7 kB

Release files / mat3ra_notebooks_utils-2026.9.18.post0.tar.gz

Download URL	mat3ra_notebooks_utils-2026.9.18.post0.tar.gz
Size	95.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`47ff8d66ea80d47a847cd79a75206884f858bfbe01b0a150ad764fd1f8328572`
BLAKE2b-256 checksum How to use checksums	`a8b3d996747b5762b6f75024cdd30a09e169c48822dbd83a161dae6c25c1d4e8`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/9.0.1 pkginfo/1.13 requests/2.34.2 requests-toolbelt/1.0.0 tqdm/4.70.1 CPython/3.10.21`

Release files / mat3ra_notebooks_utils-2026.9.18.post0-py3-none-any.whl

Download URL	mat3ra_notebooks_utils-2026.9.18.post0-py3-none-any.whl
Size	92.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1aeb11a3197d04d6f326eb019e293aabb06f89b2d3b352a6fb1722fa5ecf1f8f`
BLAKE2b-256 checksum How to use checksums	`02baf1a656dfb12225e7abaebe882fb769b319194bc1525db027501ad0d6bf15`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/9.0.1 pkginfo/1.13 requests/2.34.2 requests-toolbelt/1.0.0 tqdm/4.70.1 CPython/3.10.21`