mat3ra-api-examples 0.1.0__tar.gz

mat3ra-api-examples-0.1.0/.gitattributes

@@ -0,0 +1,17 @@
+*.csv filter=lfs diff=lfs merge=lfs -text
+*.vasp filter=lfs diff=lfs merge=lfs -text
+*.poscar filter=lfs diff=lfs merge=lfs -text
+examples/job/create_and_submit_job.ipynb    !filter !diff !merge text
+examples/job/get-file-from-job.ipynb    !filter !diff !merge text
+examples/job/ml-train-model-predict-properties.ipynb    !filter !diff !merge text
+examples/job/run-simulations-and-extract-properties.ipynb   !filter !diff !merge text
+examples/material/api_interoperability_showcase.ipynb   !filter !diff !merge text
+examples/material/create_material.ipynb !filter !diff !merge text
+examples/material/get_materials_by_formula.ipynb    !filter !diff !merge text
+examples/material/import_materials_from_materialsproject.ipynb  !filter !diff !merge text
+examples/material/import_materials_from_poscar.ipynb    !filter !diff !merge text
+examples/system/get_authentication_params.ipynb !filter !diff !merge text
+examples/workflow/get_workflows.ipynb !filter !diff !merge text
+images/*.png filter=lfs diff=lfs merge=lfs -text
+*.upf filter=lfs diff=lfs merge=lfs -text
+examples/assets/bash_workflow_template.json filter=lfs diff=lfs merge=lfs -text

mat3ra-api-examples-0.1.0/.github/workflows/check_links.yml

@@ -0,0 +1,16 @@
+name: check_links
+
+on: [push, pull_request]
+
+jobs:
+  check-links:
+    # Do not run this check if a PR is created from the same repo.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v3
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v1.8.0
+        with:
+          fail: true

mat3ra-api-examples-0.1.0/.github/workflows/cicd.yml

@@ -0,0 +1,133 @@
+name: Continuous Testing and Docs Publication
+
+on: [push]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  run-linter:
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        python-version: ["3.8.6"]
+
+    steps:
+      - name: Checkout this repository
+        uses: actions/checkout@v3
+        with:
+          lfs: true
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run pre-commit hooks
+        run: |
+          python -m pip install pre-commit
+          pre-commit run --all-files --show-diff-on-failure
+
+  publish-py-package:
+    needs: [run-linter]
+    runs-on: ubuntu-latest
+    if: github.ref_name == 'dev'
+
+    steps:
+      - name: Checkout this repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Checkout actions repository
+        uses: actions/checkout@v4
+        with:
+          repository: Exabyte-io/actions
+          token: ${{ secrets.BOT_GITHUB_TOKEN }}
+          path: actions
+
+      - name: Publish python release
+        uses: ./actions/py/publish
+        with:
+          python-version: 3.8.x
+          github-token: ${{ secrets.BOT_GITHUB_TOKEN }}
+          pypi-api-token: ${{ secrets.PYPI_API_TOKEN }}
+
+# TODO: Add back when when fixed.
+#  build-and-deploy-docs:
+#    runs-on: ubuntu-20.04
+#    strategy:
+#      matrix:
+#        python-version: ["3.8.6"]
+#    env:
+#      ACCOUNT_ID: ${{ secrets.DEMO_ACCOUNT_ID }}
+#      AUTH_TOKEN: ${{ secrets.DEMO_AUTH_TOKEN }}
+#      MATERIALS_PROJECT_API_KEY: ${{ secrets.MATERIALS_PROJECT_API_KEY }}
+#      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+#      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+#      DOCS_MAT3RA_COM_CLOUDFRONT_DISTRIBUTION_ID: ${{ secrets.DOCS_MAT3RA_COM_CLOUDFRONT_DISTRIBUTION_ID }}
+#    defaults:
+#      run:
+#        shell: bash -l {0}
+#
+#    steps:
+#      - name: Checkout this repository
+#        uses: actions/checkout@v3
+#        with:
+#          lfs: true
+#
+#      - uses: actions/setup-python@v4
+#        with:
+#          python-version: ${{ matrix.python-version }}
+#
+#      - name: Install dependencies
+#        run: |
+#          set -euo pipefail
+#
+#          python -m pip install -ve ".[localhost, docs]"
+#          python -m pip list
+#
+#      - name: Export requirements.txt
+#        run: |
+#          pip install pip-tools
+#          for extra in colab localhost dev docs; do
+#              python -m piptools compile --resolver=backtracking --extra ${extra} -o requirements-${extra}.txt pyproject.toml
+#          done
+#
+#      - name: Build documentation
+#        run : |
+#          mkdocs build -d site
+#
+#      - uses: actions/upload-artifact@v3
+#        with:
+#          name: rendered-notebooks-py${{ matrix.python-version }}
+#          path: site
+#      - uses: actions/upload-artifact@v3
+#        with:
+#          name: requirements-py${{ matrix.python-version }}
+#          path: requirements-*.txt
+#
+#      - name: Deploy documentation to Exabyte-io.github.io
+#        if: github.repository_owner == 'Exabyte-io' && github.ref_name == 'dev' && matrix.python-version == '3.8'
+#        # We pin to the SHA, not the tag, for security reasons.
+#        # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+#        uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
+#        with:
+#          github_token: ${{ secrets.GITHUB_TOKEN }}
+#          publish_branch: dev-with-documentation
+#          publish_dir: ./site
+#          destination_dir: ./docs
+#          keep_files: true  # Keep old files.
+#          force_orphan: false  # Keep git history.
+#
+#      - name: S3 Deploy
+#        if: github.repository_owner == 'Exabyte-io' && github.ref_name == 'dev' && matrix.python-version == '3.8'
+#        uses: Exabyte-io/action-s3-deploy@v3
+#        with:
+#          folder: site
+#          bucket: docs.mat3ra.com/rest-api/api-examples/rendered-notebooks
+#          bucket-region: us-west-2
+#          dist-id: ${{ env.DOCS_MAT3RA_COM_CLOUDFRONT_DISTRIBUTION_ID }}
+#          invalidation: /*
+#          no-cache: true
+#          private: true

mat3ra-api-examples-0.1.0/.github/workflows/zip_release.yml

@@ -0,0 +1,51 @@
+name: zip_release
+
+# Controls when the action will run.
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Upload Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+
+      - name: Checkout LFS Objects
+        run: git lfs checkout
+
+      - name: Zip Files
+        run: zip -r release.zip . -x ".git/*" ".github/*"
+
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Zip Archive, ${{ github.ref }}
+          draft: true
+          prerelease: false
+
+      - name: Upload Release Asset
+        id: upload-release-asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: ./release.zip
+          asset_name: release.zip
+          asset_content_type: application/zip

mat3ra-api-examples-0.1.0/.gitignore

@@ -0,0 +1,112 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+.idea
+
+# Miscellaneous
+examples/assets/Molecules_Dataset_Collection
+pw_scf.*
+examples/**/*.html
+.DS_Store

mat3ra-api-examples-0.1.0/.lycheeignore

@@ -0,0 +1,3 @@
+https://pubs.acs.org/doi/abs/10.1021/acs.nanolett.8b00670
+https://advances.sciencemag.org/content/5/9/eaax5101.abstract
+https://www.vasp.at/wiki/index.php/Input

mat3ra-api-examples-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+exclude: ^((examples|other)\/.*\/.*\.(py|poscar|csv))
+repos:
+  - repo: https://github.com/Exabyte-io/pre-commit-hooks
+    rev: 2023.6.28
+    hooks:
+      - id: ruff
+      - id: black
+      - id: black-jupyter
+        exclude: ^other\/.*\/.*\.ipynb
+      - id: isort
+      - id: mypy
+        exclude: ^examples\/config\.py
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

mat3ra-api-examples-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.1
+Name: mat3ra-api-examples
+Version: 0.1.0
+Summary: Mat3ra API Examples
+Project-URL: homepage, https://exabyte-io.github.io/api-examples
+Project-URL: documentation, https://exabyte-io.github.io/api-examples
+Project-URL: repository, https://github.com/Exabyte-io/api-examples
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: ase>=3.21.1
+Requires-Dist: exabyte-api-client>=2023.6.13.post0
+Requires-Dist: matplotlib>=3.4.1
+Requires-Dist: pandas>=1.5.3
+Requires-Dist: pymatgen>=2023.5.31
+Provides-Extra: colab
+Requires-Dist: mat3ra-api-examples; extra == "colab"
+Provides-Extra: jupyterlab
+Requires-Dist: jupyterlab>=3.0.17; extra == "jupyterlab"
+Requires-Dist: nbconvert>=6.0.7; extra == "jupyterlab"
+Provides-Extra: localhost
+Requires-Dist: mat3ra-api-examples[jupyterlab]; extra == "localhost"
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.3.3; extra == "dev"
+Requires-Dist: pip-tools>=6.13.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.4.3; extra == "docs"
+Requires-Dist: mkdocs-material>=9.1.17; extra == "docs"
+Requires-Dist: mkdocs-same-dir>=0.1.2; extra == "docs"
+Requires-Dist: mkdocs-exclude>=1.0.2; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.24.1; extra == "docs"
+Requires-Dist: nbstripout>=0.6.1; extra == "docs"
+
+# Mat3ra API Examples
+
+## Contents of this Repository
+
+Below, we list the contents of this repository, in roughly the order that a user might want to go through it in order to learn how our API works.
+
+| Folder            | Notebook                                | Description |
+| ------------------|-----------------------------------------| ----------- |
+| [Examples/System](examples/system/)     | [Get Authentication Params](examples/system/get_authentication_params.ipynb)               | Demonstrates how to programatically find your user ID and access token, which is to [authenticate](https://docs.mat3ra.com/rest-api/authentication/) for many portions of the Mat3ra API.
+| [Examples/Workflow](examples/workflow/) | [Get Workflows](examples/workflow/get_workflows.ipynb)                           | Walks through how to [query](https://docs.mat3ra.com/rest-api/query-structure/) the Mat3ra API to programatically search for workflows. In this example, we search for workflows that calculate the total energy of a material.
+| [Examples/Workflow](examples/workflow/) | [Quantum Espresso Workflow and Job](examples/workflow/qe_scf_calculation.ipynb)  | Create Quantum Espresso workflow starting from QE input file; create and submit job; after the job is finished, download output file, and finally perform postprocessing analysis.
+| [Examples/Material](examples/material/) | [Get Materials by Formula](examples/material/get_materials_by_formula.ipynb)                | Shows how [queries](https://docs.mat3ra.com/rest-api/query-structure/) can be made to search for materials stored on your account by their formula. In this example, we search for a system containing Si.
+| [Examples/Material](examples/material/) | [Create Material](examples/material/create_material.ipynb)                         | Gives an overview of how materials can be generated in [JSON format](https://docs.mat3ra.com/materials/data/) and uploaded to your user account. In this example, we create an FCC Si crystal and upload it.
+| [Examples/Material](examples/material/) | [Import Materials from Materials Project](examples/material/import_materials_from_materialsproject.ipynb) | Demonstrates how materials can be imported from [Materials Project](https://materialsproject.org/about), if their Materials Project ID is known. In this example, we import monoclinic and hexagonal SiGe cells.
+| [Examples/Material](examples/material/) | [Import Materials from Poscar](examples/material/upload_materials_from_file_poscar.ipynb)            | Provides an example of how materials can be imported directly from Poscar files (a common chemical file format best-known [for its use in VASP](https://www.vasp.at/wiki/index.php/Input)). In this example, we import the unit cell of SiGe.
+| [Examples/Material](examples/material/) | [Interoperability between Mat3ra and Materials Project](examples/material/api_interoperability_showcase.ipynb)            | In this notebook, we showcase a major advantage of APIs: interoperability. We begin by performing a query using the [Materials Project](https://materialsproject.org) API for all systems containing Iron and Oxygen. We then filter our results (for demonstraiton purposes, we keep only the first 10 materials found). Finally, we upload our results to the Mat3ra platform, where further calculations could be performed to characterize these materials.
+| [Examples/Job](examples/job/)            | [Create and Submit Job](examples/job/create_and_submit_job.ipynb)                   | Shows how to use the Mat3ra API to [create jobs](https://docs.mat3ra.com/jobs/data/) and run them on our cluster. In this example, we run a DFT calculation to get the total energy of an FCC Si unit cell using Quantum Espresso.
+| [Examples/Job](examples/job/)            | [Get File from Job](examples/job/get-file-from-job.ipynb) | Guides you through using the Mat3ra API to query for a list of files produced by a job, describes the metadata assigned to each file, and ends by demonstrating how to download any remote file generated by a job to the local disk.
+| [Examples/Job](examples/job/)            | [Run Simulations and Extract Properties](examples/job/run-simulations-and-extract-properties.ipynb)  | Leads you through the process of copying a [bank workflow](https://docs.mat3ra.com/workflows/bank/) to your account and using it to automatically calculate the [properties](https://docs.mat3ra.com/properties/overview/) of multiple materials. In this example, we determine the [band gap](https://docs.mat3ra.com/properties-directory/non-scalar/band-gaps/) of Si and Ge.
+| [Examples/Job](examples/job/)            | [ML - Train Model Predict Properties](examples/job/ml-train-model-predict-properties.ipynb)     | Walks you through automated dataset generation and the training/prediction of material properties using [machine learning](https://docs.mat3ra.com/software-directory/overview/#machine-learning). In this example, we calculate the band gaps of Si and SiGe, and using various materials properties as descriptors, train a model to predict their band gaps. Finally, we use this trained model to predict the band gap of Ge.
+
+
+
+## Setup
+
+NOTE: tested with Python version 3.8 and 3.10, please assert that the virtual environment is created with it. Use [`pyenv`](https://github.com/pyenv/pyenv#installation) to manage Python versions.
+
+Follow the steps below in order to setup and view the Jupyter notebooks:
+
+0. [Install git-lfs](https://help.github.com/articles/installing-git-large-file-storage/) [[3](#links)] in order to get access to the source code and notebook files.
+
+1. Clone repository:
+
+    ```bash
+    git clone https://github.com/Exabyte-io/api-examples.git
+    ```
+
+    Or, if you have set up SSH keys
+
+    ```bash
+    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.
+
+3. Install [virtualenv](https://virtualenv.pypa.io/en/stable/) using [pip](https://pip.pypa.io/en/stable/) if not already present:
+
+    ```bash
+    pip install virtualenv
+    ```
+
+4. Create virtual environment and install required packages:
+
+    ```bash
+    cd api-examples
+    virtualenv .env
+    source .env/bin/activate
+    pip install -e ."[localhost]"
+    ```
+
+5. 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:
+
+    ```bash
+    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](https://platform.mat3ra.com/register) to obtain one.
+
+2. Open [settings](utils/settings.json) and adjust it to provide the API authentication parameters. See the [corresponding example](examples/system/get_authentication_params.ipynb) to learn how to obtain the authentication parameters. It is also possible to generate an API token by logging in to [Mat3ra platform](https://platform.mat3ra.com/), navigating to the Account Preferences, and clicking the 'Generate new token' button under API Tokens. More details can be found [here](https://docs.mat3ra.com/accounts/ui/preferences/api/).
+
+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](examples/system/get_authentication_params.ipynb) one by reusing the kernel from the first notebook.
+
+  <img src="images/reusable-kernel.png" width="250px" />
+
+NOTE: The Materials Project API key should be obtained from [https://legacy.materialsproject.org/open](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](#links)].
+
+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](examples/material/get_materials_by_formula.ipynb) example.
+
+3. We use post-save hooks to automatically convert notebooks to python scripts. See [config](examples/config.py) 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](#links)]. Please follow this convention.
+
+4. Apply code formatting by installing development requirements as follows:
+
+    ```bash
+    pip install -e ."[dev]"
+    pre-commit install
+    pre-commit run --all-files
+    ```
+
+    Check more details about `pre-commit` [here](https://pre-commit.com/).
+
+## Links
+
+1. Mat3ra.com RESTful API, description in the online documentation: [link](https://docs.mat3ra.com/rest-api/overview/)
+2. Jupyter.org, official website: [link](https://jupyter.org/)
+3. Git Large File Storage, official website: [link](https://git-lfs.github.com/)
+4. GitHub Standard Fork & Pull Request Workflow, online explanation: [link](https://gist.github.com/Chaser324/ce0505fbed06b947d962)

mat3ra-api-examples-0.1.0/README.md

@@ -0,0 +1,114 @@
+# Mat3ra API Examples
+
+## Contents of this Repository
+
+Below, we list the contents of this repository, in roughly the order that a user might want to go through it in order to learn how our API works.
+
+| Folder            | Notebook                                | Description |
+| ------------------|-----------------------------------------| ----------- |
+| [Examples/System](examples/system/)     | [Get Authentication Params](examples/system/get_authentication_params.ipynb)               | Demonstrates how to programatically find your user ID and access token, which is to [authenticate](https://docs.mat3ra.com/rest-api/authentication/) for many portions of the Mat3ra API.
+| [Examples/Workflow](examples/workflow/) | [Get Workflows](examples/workflow/get_workflows.ipynb)                           | Walks through how to [query](https://docs.mat3ra.com/rest-api/query-structure/) the Mat3ra API to programatically search for workflows. In this example, we search for workflows that calculate the total energy of a material.
+| [Examples/Workflow](examples/workflow/) | [Quantum Espresso Workflow and Job](examples/workflow/qe_scf_calculation.ipynb)  | Create Quantum Espresso workflow starting from QE input file; create and submit job; after the job is finished, download output file, and finally perform postprocessing analysis.
+| [Examples/Material](examples/material/) | [Get Materials by Formula](examples/material/get_materials_by_formula.ipynb)                | Shows how [queries](https://docs.mat3ra.com/rest-api/query-structure/) can be made to search for materials stored on your account by their formula. In this example, we search for a system containing Si.
+| [Examples/Material](examples/material/) | [Create Material](examples/material/create_material.ipynb)                         | Gives an overview of how materials can be generated in [JSON format](https://docs.mat3ra.com/materials/data/) and uploaded to your user account. In this example, we create an FCC Si crystal and upload it.
+| [Examples/Material](examples/material/) | [Import Materials from Materials Project](examples/material/import_materials_from_materialsproject.ipynb) | Demonstrates how materials can be imported from [Materials Project](https://materialsproject.org/about), if their Materials Project ID is known. In this example, we import monoclinic and hexagonal SiGe cells.
+| [Examples/Material](examples/material/) | [Import Materials from Poscar](examples/material/upload_materials_from_file_poscar.ipynb)            | Provides an example of how materials can be imported directly from Poscar files (a common chemical file format best-known [for its use in VASP](https://www.vasp.at/wiki/index.php/Input)). In this example, we import the unit cell of SiGe.
+| [Examples/Material](examples/material/) | [Interoperability between Mat3ra and Materials Project](examples/material/api_interoperability_showcase.ipynb)            | In this notebook, we showcase a major advantage of APIs: interoperability. We begin by performing a query using the [Materials Project](https://materialsproject.org) API for all systems containing Iron and Oxygen. We then filter our results (for demonstraiton purposes, we keep only the first 10 materials found). Finally, we upload our results to the Mat3ra platform, where further calculations could be performed to characterize these materials.
+| [Examples/Job](examples/job/)            | [Create and Submit Job](examples/job/create_and_submit_job.ipynb)                   | Shows how to use the Mat3ra API to [create jobs](https://docs.mat3ra.com/jobs/data/) and run them on our cluster. In this example, we run a DFT calculation to get the total energy of an FCC Si unit cell using Quantum Espresso.
+| [Examples/Job](examples/job/)            | [Get File from Job](examples/job/get-file-from-job.ipynb) | Guides you through using the Mat3ra API to query for a list of files produced by a job, describes the metadata assigned to each file, and ends by demonstrating how to download any remote file generated by a job to the local disk.
+| [Examples/Job](examples/job/)            | [Run Simulations and Extract Properties](examples/job/run-simulations-and-extract-properties.ipynb)  | Leads you through the process of copying a [bank workflow](https://docs.mat3ra.com/workflows/bank/) to your account and using it to automatically calculate the [properties](https://docs.mat3ra.com/properties/overview/) of multiple materials. In this example, we determine the [band gap](https://docs.mat3ra.com/properties-directory/non-scalar/band-gaps/) of Si and Ge.
+| [Examples/Job](examples/job/)            | [ML - Train Model Predict Properties](examples/job/ml-train-model-predict-properties.ipynb)     | Walks you through automated dataset generation and the training/prediction of material properties using [machine learning](https://docs.mat3ra.com/software-directory/overview/#machine-learning). In this example, we calculate the band gaps of Si and SiGe, and using various materials properties as descriptors, train a model to predict their band gaps. Finally, we use this trained model to predict the band gap of Ge.
+
+
+
+## Setup
+
+NOTE: tested with Python version 3.8 and 3.10, please assert that the virtual environment is created with it. Use [`pyenv`](https://github.com/pyenv/pyenv#installation) to manage Python versions.
+
+Follow the steps below in order to setup and view the Jupyter notebooks:
+
+0. [Install git-lfs](https://help.github.com/articles/installing-git-large-file-storage/) [[3](#links)] in order to get access to the source code and notebook files.
+
+1. Clone repository:
+
+    ```bash
+    git clone https://github.com/Exabyte-io/api-examples.git
+    ```
+
+    Or, if you have set up SSH keys
+
+    ```bash
+    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.
+
+3. Install [virtualenv](https://virtualenv.pypa.io/en/stable/) using [pip](https://pip.pypa.io/en/stable/) if not already present:
+
+    ```bash
+    pip install virtualenv
+    ```
+
+4. Create virtual environment and install required packages:
+
+    ```bash
+    cd api-examples
+    virtualenv .env
+    source .env/bin/activate
+    pip install -e ."[localhost]"
+    ```
+
+5. 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:
+
+    ```bash
+    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](https://platform.mat3ra.com/register) to obtain one.
+
+2. Open [settings](utils/settings.json) and adjust it to provide the API authentication parameters. See the [corresponding example](examples/system/get_authentication_params.ipynb) to learn how to obtain the authentication parameters. It is also possible to generate an API token by logging in to [Mat3ra platform](https://platform.mat3ra.com/), navigating to the Account Preferences, and clicking the 'Generate new token' button under API Tokens. More details can be found [here](https://docs.mat3ra.com/accounts/ui/preferences/api/).
+
+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](examples/system/get_authentication_params.ipynb) one by reusing the kernel from the first notebook.
+
+  <img src="images/reusable-kernel.png" width="250px" />
+
+NOTE: The Materials Project API key should be obtained from [https://legacy.materialsproject.org/open](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](#links)].
+
+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](examples/material/get_materials_by_formula.ipynb) example.
+
+3. We use post-save hooks to automatically convert notebooks to python scripts. See [config](examples/config.py) 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](#links)]. Please follow this convention.
+
+4. Apply code formatting by installing development requirements as follows:
+
+    ```bash
+    pip install -e ."[dev]"
+    pre-commit install
+    pre-commit run --all-files
+    ```
+
+    Check more details about `pre-commit` [here](https://pre-commit.com/).
+
+## Links
+
+1. Mat3ra.com RESTful API, description in the online documentation: [link](https://docs.mat3ra.com/rest-api/overview/)
+2. Jupyter.org, official website: [link](https://jupyter.org/)
+3. Git Large File Storage, official website: [link](https://git-lfs.github.com/)
+4. GitHub Standard Fork & Pull Request Workflow, online explanation: [link](https://gist.github.com/Chaser324/ce0505fbed06b947d962)

mat3ra-api-examples-0.1.0/examples/assets/README.md

@@ -0,0 +1,7 @@
+# Assets for Notebooks
+
+This directory contains various files for the example notebooks.
+
+- `mp-978534.poscar` contains a SiGe structure from [https://materialsproject.org/materials/mp-978534/](https://materialsproject.org/materials/mp-978534/).
+- `bash_workflow_template.json` contains the template JSON schema of Mat3ra workflow.
+- `Si.pz-vbc.UPF` is the pseudo potential file of silicon used in the Quantum Espresso workflow example.

mat3ra-api-examples-0.1.0/examples/assets/Si.pz-vbc.UPF

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d7b4ab71aaf8e4a8b267f1349df21ef5a851d0da1d5f210bb7994ce6afb9f3e3
+size 74553