Merge branch 'dev'

Author: kks32

.gitignore

@@ -175,3 +175,4 @@ cython_debug/
 *.log
 *.sqlite
 
+.aider*

dapi/client.py

@@ -311,8 +311,8 @@ def generate_request(
         self,
         app_id: str,
         input_dir_uri: str,
-        script_filename: str,
         # --- Optional Overrides ---
+        script_filename: Optional[str] = None,
         app_version: Optional[str] = None,
         job_name: Optional[str] = None,
         description: Optional[str] = None,
@@ -344,7 +344,8 @@ def generate_request(
         Args:
             app_id (str): The ID of the Tapis application to use for the job.
             input_dir_uri (str): Tapis URI to the input directory containing job files.
-            script_filename (str): Name of the main script file to execute.
+            script_filename (str, optional): Name of the main script file to execute.
+                If None, no script parameter is added (suitable for apps like OpenFOAM).
             app_version (str, optional): Specific app version. If None, uses latest.
             job_name (str, optional): Custom job name. If None, auto-generates one.
             description (str, optional): Job description. If None, uses app description.

dapi/jobs.py

@@ -4,6 +4,36 @@ The main client interface for all DAPI functionality. DSClient provides organize
 
 ::: dapi.client.DSClient
 
+## Accessing the Raw Tapis Client
+
+For advanced use cases or accessing Tapis APIs not wrapped by dapi, you can get the underlying Tapis client:
+
+```python
+from dapi import DSClient
+
+# Initialize DSClient
+ds = DSClient()
+
+# Access the raw Tapis client
+tapis_client = ds.tapis
+
+# Use raw Tapis APIs directly
+raw_apps = tapis_client.apps.getApps(search="*opensees*")
+systems = tapis_client.systems.getSystems()
+jobs = tapis_client.jobs.getJobList()
+```
+
+### When to Use the Raw Tapis Client
+
+- Access Tapis APIs not yet wrapped by dapi
+- Use advanced search parameters not exposed by dapi  
+- Implement custom functionality
+- Debug or troubleshoot API calls
+- Access experimental or new Tapis features
+
+!!! warning
+    When using the raw Tapis client, you'll need to handle errors and data formatting yourself. The dapi wrapper provides error handling and user-friendly formatting.
+
 ## Service Interfaces
 
 The DSClient provides access to different DesignSafe services through specialized interface classes:

docs/api/client.md

@@ -307,6 +307,27 @@ print(f"NGL database has {df.iloc[0, 0]} sites")
 print("✅ All authentication successful!")
 ```
 
+## 🔧 Troubleshooting
+
+### JWT Token Expiration
+
+If you encounter JWT token expiration errors during long-running sessions, you'll see an error like:
+
+```
+UnauthorizedError: message: b'TAPIS_SECURITY_JWT_EXPIRED Exception message: JWT expired at 2025-06-09T08:51:38Z. Current time: 2025-06-09T12:06:54Z, a difference of 11716617 milliseconds. Allowed clock skew: 0 milliseconds. Claims: iss: https://designsafe.tapis.io/v3/tokens sub: username@designsafe tapis/tenant_id: designsafe tapis/username: username tapis/account_type: user'
+```
+
+**Solution:** Simply reinitialize your DSClient to refresh the authentication tokens:
+
+```python
+# Reinitialize the client to refresh tokens
+ds = DSClient()
+```
+
+This will automatically handle token refresh and you can continue with your work.
+
+**Why this happens:** Tapis authentication tokens have a limited lifespan for security purposes. Long-running Jupyter notebooks or scripts may encounter this after several hours of use.
+
 ## ➡️ Next Steps
 
 After setting up authentication:

docs/authentication.md

@@ -8,6 +8,7 @@ Welcome to the DAPI examples collection! These comprehensive tutorials demonstra
 Choose an example above and click "Try on DesignSafe" to begin your computational research journey!
 
 Each example is self-contained and includes:
+
 - ✅ Complete, runnable code
 - ✅ Step-by-step explanations
 - ✅ Real-world applications

docs/examples.md

@@ -0,0 +1,225 @@
+# App Discovery and Management
+
+This guide demonstrates how to discover and examine Tapis applications available on DesignSafe using the dapi library.
+
+## Basic Setup
+
+```python
+from dapi import DSClient
+
+# Initialize the client (will prompt for credentials if needed)
+ds = DSClient()
+```
+
+## Finding Applications
+
+### Find All Available Apps
+
+```python
+# Get a list of all available applications
+all_apps = ds.apps.find("", verbose=False)
+print(f"Found {len(all_apps)} total apps.")
+```
+
+### Search for Specific Apps
+
+```python
+# Search for applications containing "mpm" in the name
+mpm_apps = ds.apps.find("mpm", verbose=True)
+```
+
+The `verbose=True` option will display a formatted list of matching applications with their versions and owners.
+
+### Search for Other Common Applications
+
+```python
+# Find MATLAB apps
+matlab_apps = ds.apps.find("matlab", verbose=True)
+
+# Find OpenSees apps
+opensees_apps = ds.apps.find("opensees", verbose=True)
+
+# Find ADCIRC apps
+adcirc_apps = ds.apps.find("adcirc", verbose=True)
+
+# Find OpenFOAM apps
+openfoam_apps = ds.apps.find("openfoam", verbose=True)
+```
+
+## Getting Application Details
+
+### Basic App Information
+
+```python
+# Get detailed information for a specific application
+app_id = "opensees-express"
+app_details = ds.apps.get_details(app_id, verbose=True)
+
+if app_details:
+    print(f"App ID: {app_details.id}")
+    print(f"Version: {app_details.version}")
+    print(f"Description: {app_details.description}")
+    print(f"Owner: {app_details.owner}")
+    print(f"Execution System: {app_details.jobAttributes.execSystemId}")
+else:
+    print(f"App '{app_id}' not found")
+```
+
+### Understanding App Parameters
+
+Applications define their input requirements through parameters. Here's how to examine them:
+
+```python
+app_details = ds.apps.get_details("opensees-express")
+job_attrs = app_details.jobAttributes
+param_set = job_attrs.parameterSet
+
+# Check file inputs
+print("File Inputs:")
+for file_input in job_attrs.fileInputs:
+    print(f"  - {file_input.name}: {file_input.description}")
+
+# Check app arguments
+print("\nApp Arguments:")
+for arg in param_set.appArgs:
+    print(f"  - {arg.name}: {arg.description}")
+
+# Check environment variables
+print("\nEnvironment Variables:")
+for env_var in param_set.envVariables:
+    print(f"  - {env_var.key}: {env_var.description}")
+    if hasattr(env_var, 'enum_values') and env_var.enum_values:
+        print(f"    Options: {list(env_var.enum_values.keys())}")
+```
+
+### Resource Requirements
+
+```python
+# Check default resource requirements
+job_attrs = app_details.jobAttributes
+print(f"Default node count: {job_attrs.nodeCount}")
+print(f"Default cores per node: {job_attrs.coresPerNode}")
+print(f"Default memory (MB): {job_attrs.memoryMB}")
+print(f"Default max minutes: {job_attrs.maxMinutes}")
+print(f"Default queue: {job_attrs.execSystemLogicalQueue}")
+```
+
+## Working with App Data as DataFrames
+
+For analysis and comparison, you can convert app data to pandas DataFrames:
+
+```python
+import pandas as pd
+
+# Get all apps and convert to DataFrame
+all_apps = ds.apps.find("", verbose=False)
+
+# Extract basic app information
+app_data = []
+for app in all_apps:
+    app_data.append({
+        'id': app.id,
+        'version': app.version,
+        'owner': app.owner,
+        'description': app.description,
+        'enabled': app.enabled,
+        'execution_system': getattr(app.jobAttributes, 'execSystemId', 'N/A'),
+        'max_minutes': getattr(app.jobAttributes, 'maxMinutes', 'N/A'),
+        'node_count': getattr(app.jobAttributes, 'nodeCount', 'N/A'),
+        'cores_per_node': getattr(app.jobAttributes, 'coresPerNode', 'N/A'),
+    })
+
+apps_df = pd.DataFrame(app_data)
+print(apps_df.head())
+
+# Filter for specific types of applications
+simulation_apps = apps_df[apps_df['description'].str.contains('simulation', case=False, na=False)]
+print(f"\nFound {len(simulation_apps)} simulation apps")
+```
+
+## Advanced: Accessing the Raw Tapis Client
+
+If you need to access Tapis APIs that aren't wrapped by dapi, you can get the underlying Tapis client:
+
+```python
+# Get the raw Tapis client for advanced operations
+tapis_client = ds.tapis
+
+# Example: Get raw app details using Tapis client directly
+raw_app_details = tapis_client.apps.getApp(appId="opensees-express")
+print(f"Raw app data: {raw_app_details}")
+
+# Example: List apps with custom parameters
+raw_apps = tapis_client.apps.getApps(search="*mpm*", listType="ALL")
+print(f"Found {len(raw_apps)} raw apps")
+
+# Example: Access other Tapis services
+systems = tapis_client.systems.getSystems()
+print(f"Available systems: {len(systems)}")
+```
+
+### When to Use the Raw Tapis Client
+
+Use `ds.tapis` when you need to:
+
+- Access Tapis APIs not yet wrapped by dapi
+- Use advanced search parameters not exposed by dapi
+- Implement custom functionality
+- Debug or troubleshoot API calls
+- Access experimental or new Tapis features
+
+!!! warning "Using Raw Tapis Client"
+    When using the raw Tapis client, you'll need to handle errors and data formatting yourself. The dapi wrapper provides error handling and user-friendly formatting that you'll lose with direct Tapis calls.
+
+## Common App Categories
+
+Here are some common application categories available on DesignSafe:
+
+```python
+# Structural analysis applications
+structural_keywords = ["opensees", "abaqus", "ansys", "ls-dyna"]
+
+# Fluid dynamics applications  
+fluid_keywords = ["openfoam", "adcirc", "swan"]
+
+# Geotechnical applications
+geo_keywords = ["mpm", "plaxis", "flac"]
+
+# Materials applications
+materials_keywords = ["lammps", "matlab"]
+
+# Search for each category
+for category, keywords in [
+    ("Structural", structural_keywords),
+    ("Fluid Dynamics", fluid_keywords), 
+    ("Geotechnical", geo_keywords),
+    ("Materials", materials_keywords)
+]:
+    print(f"\n{category} Applications:")
+    for keyword in keywords:
+        apps = ds.apps.find(keyword, verbose=False)
+        if apps:
+            print(f"  {keyword}: {len(apps)} apps found")
+```
+
+## Next Steps
+
+After discovering applications, you can:
+
+1. **[Submit jobs](../jobs.md)** using the discovered applications
+2. **[Explore job examples](mpm.md)** for specific workflows
+3. **[Check system resources](../api/systems.md)** for execution requirements
+4. **[Manage files](../api/files.md)** for job inputs and outputs
+
+## Troubleshooting
+
+### App Not Found
+If an application isn't found, it might be:
+- Disabled temporarily
+- Only available to specific users
+- Spelled differently than expected
+
+Try broader searches or contact DesignSafe support.
+
+### Access Issues
+Some applications might require special permissions or allocations. Check with your project team or DesignSafe support if you can't access expected applications.

docs/examples/apps.md

@@ -4,6 +4,10 @@ This comprehensive example demonstrates how to submit and monitor a Material Poi
 
 [![Try on DesignSafe](https://raw.githubusercontent.com/DesignSafe-CI/dapi/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/dapi/mpm/mpm-minimal.ipynb)
 
+> More detailed example
+[![Try on DesignSafe](https://raw.githubusercontent.com/DesignSafe-CI/dapi/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/dapi/mpm/mpm.ipynb)
+
+
 ## 🎯 Overview
 
 This example covers: