DesignSafe API (dapi)

dapi is a Python library for submitting, running, and monitoring TAPIS v3 jobs on DesignSafe via Jupyter Notebooks or the command line.

Features

Jobs

• Generate TAPIS v3 job requests with automatic app parameter mapping
• Submit, monitor (with progress bars), and manage jobs
• Access and download job outputs
• Discover and explore available DesignSafe applications

TMS Credentials

• Establish, check, and revoke SSH keys on TACC execution systems (Frontera, Stampede3, LS6)
• Works from any environment -- DesignSafe JupyterHub, command line, CI/CD

Files

• Translate DesignSafe paths (/MyData, /CommunityData, /projects) to TAPIS URIs
• Upload, download, and list files on DesignSafe storage

Database

Connects to SQL databases on DesignSafe:

Define the following environment variables:

{env_prefix}DB_USER
{env_prefix}DB_PASSWORD
{env_prefix}DB_HOST
{env_prefix}DB_PORT

For e.g., to add the environment variable NGL_DB_USER edit ~/.bashrc, ~/.zshrc, or a similar shell-specific configuration file for the current user and add export NGL_DB_USER="dspublic".

Installation

pip install dapi

To install the development version:

pip install git+https://github.com/DesignSafe-CI/dapi.git@dev --quiet

In Jupyter notebooks:

%pip install dapi --quiet

To test the latest dev branch in a notebook:

%pip uninstall dapi --yes
%pip install git+https://github.com/DesignSafe-CI/dapi.git@dev --quiet

For local development (editable install — changes to source are reflected immediately):

pip install -e .

Quick Start

Authentication

Create a .env file with your DesignSafe credentials:

DESIGNSAFE_USERNAME=your_username
DESIGNSAFE_PASSWORD=your_password

Setup and submit a job

from dapi import DSClient

# Authenticate
client = DSClient()

# Establish TMS credentials (one-time per system)
client.systems.establish_credentials("frontera")

# Submit a job
job_request = client.jobs.generate(
    app_id="matlab-r2023a",
    input_dir_uri="/MyData/analysis/input/",
    script_filename="run_analysis.m",
    max_minutes=30,
    allocation="your_allocation",
)
job = client.jobs.submit(job_request)
final_status = job.monitor()

Database

from dapi import DSClient

client = DSClient()
df = client.db.ngl.read_sql("SELECT * FROM SITE LIMIT 10")
print(df)

Support

For any questions, issues, or feedback submit an issue.

Development

Install uv, then:

uv venv
uv pip install -e ".[dev]"

Run tests:

pytest tests/ -v

Build the package:

uv build

Documentation

Documentation uses Jupyter Book v2. To build and serve locally:

uv pip install -e ".[docs]"
jupyter-book start

License

dapi is licensed under the MIT License.

Authors

• Prof. Krishna Kumar, University of Texas at Austin
• Prof. Pedro Arduino, University of Washington
• Prof. Scott Brandenberg, University of California Los Angeles