Create a new Materials Commons project

This example demonstrates creating a new Materials Commons project from a Jupyter notebook. To try running it locally, download the notebook from here.

To install the necessary dependencies (requires Python 3):

pip install materials-commons-cli


Cloning a project

"Cloning" a project creates a local directory which is used as a place to upload and download project files. There are three construction options:

  1. Clone the project in a temporary directory (default)
  2. Clone the project in a particular location or open the project if it already exists. This option makes use of the "parent_path" and "name" constructor arguments to specify where the local project directory will be constructed if it doesn't already exist.
  3. Open an existing local cloned project. This option uses the "path" constructor argument to It can be at a particular location that a user chooses to reuse (by constructing with the

Example 1: Clone the project - using a temporary directory

This example clones the project using a temporary directory. Downloaded files will be eventually be cleaned up by the system when the ClonedObject instance is no longer in use.

Example 2: Clone the project - specifying the location

This example clones the project to ~/mc_projects/ExampleProjectFromJupyter.

Example 3: Open an existing cloned project

This example opens a local project that has already been cloned.

Using the ClonedProject

The ClonedProject instance provides access to Client and Project objects from the Materials Commons API (materials_commons.api) along with the location of the cloned local project directory local_path.

File transfer

The ClonedProject instance from the CLI also provides methods for uploading and downloading files using features beyond those included in materials_commons.api.

For example, transfers can include checks to skip transferring files that are equivalent, support recursive upload and download, globus transfer, etc.

Other methods implemented by the CLI will be added to ClonedProject in the future.

Setup for upload examples:

This creates a directory and writes some files used in the upload examples.

Upload one file

By default, files that already exist will be skipped

Upload multiple files

Upload files and directories, recursively

Uploading the notebook itself / use of "upload_as"

It is possible to upload a notebook, from within the notebook itself. To do so, we can use the "upload_as" option which allows uploading files that do not exist in the local cloned project directory. The following cells demonstrate getting the notebook's name, nb_name, and then uploading the notebook itself to the Materials Commons project. It is placed in a "notebooks" directory. Note that it uploads the last saved version of the notebook, not the current state.

Note: Getting the notebook file path from `os.path.join(os.getcwd(), nb_name)` may not work in all cases

Setup for download examples:

This removes the existing local files and directories to demonstrate downloading from Materials Commons.

Download one file

By default, files that already exist will be skipped

Download multiple files

Download files and directories, recursively

Download with different name

Using Globus file transfer

Monitor transfer status

Finish the transfer

Example cleanup

The delete_project call will delete a project on Materials Commons.