DAPI - DesignSafe API

Welcome to the DesignSafe API (dapi) documentation!

dapi is a Python library that simplifies the process of submitting, running, and monitoring TAPIS v3 jobs on DesignSafe via Jupyter Notebooks. It provides high-level, user-friendly interfaces for working with DesignSafe resources and research databases.

✨ Key Features

🚀 Job Management

• Simple Job Submission: Submit computational jobs with minimal configuration
• Real-time Monitoring: Track job progress with interactive progress bars
• Output Management: Easily access and download job results
• Application Discovery: Find and explore available DesignSafe applications

📊 Database Access

• Research Databases: Connect to DesignSafe research databases (NGL, Earthquake Recovery, VP)
• SQL Queries: Execute SQL queries and get results as pandas DataFrames
• Automatic Connection Management: Handles database connections and credentials

📁 File Operations

• Path Translation: Convert DesignSafe paths (/MyData, /projects) to TAPIS URIs
• File Management: Upload, download, and list files on DesignSafe storage
• Path Verification: Validate that paths exist before using them

🔐 Authentication

• Simplified Auth: Easy authentication with DesignSafe credentials
• Multiple Methods: Support for environment variables, .env files, and interactive input
• Secure: Handles credentials securely with encrypted storage

🏃‍♂️ Quick Start

Get started with dapi in just a few lines:

from dapi import DSClient

# Initialize client (handles authentication automatically)
client = DSClient()

# Submit a job
job_request = client.jobs.generate_request(
    app_id="matlab-r2023a",
    input_dir_uri="/MyData/analysis/input/",
    script_filename="run_analysis.m"
)
job = client.jobs.submit_request(job_request)

# Monitor progress
final_status = job.monitor()

# Query research databases
df = client.db.ngl.read_sql("SELECT * FROM SITE LIMIT 10")

📖 Getting Started

• Installation: Install dapi and set up your environment
• Authentication: Configure credentials and authentication
• Quick Start: Get up and running in 5 minutes

📚 User Guide

• Jobs: Submit and monitor computational jobs
• Database Access: Query DesignSafe research databases

🎯 Examples

• MPM Job Submission: Material Point Method workflow
• Database Queries: Research data analysis examples

💡 Use Cases

Research Computing

• Submit OpenSees, MATLAB, Python, and other computational jobs
• Monitor job execution with real-time status updates
• Access job outputs and results efficiently

Data Analysis

• Query large research databases with SQL
• Analyze earthquake, geotechnical, and structural data
• Export results to pandas DataFrames for further analysis

File Management

• Organize and manage research data on DesignSafe
• Transfer files between local machines and DesignSafe storage
• Collaborate on data with project teams

🆘 Support

• Issues: Report bugs or request features on GitHub Issues
• Documentation: Comprehensive guides and API reference
• Community: Connect with other users on DesignSafe forums

📄 License

dapi is licensed under the MIT License.