AmSC Interfaces
The AmSC Interfaces include a Web Portal for graphical interactions, collection of REST API services, and a Python client. The Python client is a unified SDK for interacting with American Science Cloud REST APIs. It supports data catalog operations, remote job submission via the IRI API, and filesystem access across ALCF and NERSC facilities.
Getting Started with the AmSC Python Client
Authentication (Currently Globus-only)
Throughout the use of this tutorial, the Python client may ask you to log in with a Globus account by providing a URL on the command line. You will need the following accounts to proceed:
- Globus (any) — Required for all AmSC-hosted services, e.g. data catalog, MLFlow, ClearML, etc.
- Globus (specific facility) — When using IRI or Data Transfer, you must authenticate with each account involved in the transfer, e.g. ALCF account when submitting jobs to ALCF via IRI.
Prerequisites
- Python 3.10+
- A Globus account
- For facility access (e.g. ALCF, NERSC, OLCF): a facility account, an active allocation, and IRI API allowlist access (contact your facility's support team and request access, providing your local facility account name)
Tutorial Notebooks
All notebooks are available in the public amsc-client-tutorial GitHub repository.
| Notebook | Description | Auth Required |
|---|---|---|
| Catalog Explorer | Browse, search, and filter the AmSC data catalog | Globus (AmSC) |
| Catalog Tutorial | Create, update, search, and delete catalog entities | Globus (AmSC) + write access |
| ALCF Facility Tutorial | Connect to ALCF, list resources, submit jobs to Polaris, and read output via the filesystem API | Globus (facility — ALCF) |
| Filesystem Tutorial | Filesystem operations on facility storage: ls, head, tail, stat, cp, mv, mkdir | Globus (facility — ALCF or NERSC) |
| NERSC Facility Tutorial | NERSC facility setup and job submission | Globus (facility — NERSC) |
The repository also contains reference guides for AI-agent workflows.
Installation
See the repository README for installation instructions: cloning the repo, setting up a virtual environment, installing dependencies, and launching Jupyter.
1. Clone this repository
git clone https://github.com/amsc-interfaces/amsc-client-tutorial.git
cd amsc-client-tutorial
2. Create a virtual environment
python -m venv venv
source venv/bin/activate
3. Install dependencies
pip install -r requirements.txt
Internal Resources
The following links require an AmSC Google Workspace account to access.