Skip to content

Commit cbc3910

Browse files
kks32kks32
committed
Documentation
1 parent ebeb562 commit cbc3910

5 files changed

Lines changed: 215 additions & 2 deletions

File tree

‎docs/apps.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Apps
2+
3+
## Find apps
4+
5+
Search by name. Use an empty string to list everything.
6+
7+
```python
8+
from dapi import DSClient
9+
ds = DSClient()
10+
11+
ds.apps.find("matlab")
12+
# Found 3 matching apps:
13+
# - matlab-r2023a (Version: 1.0, Owner: designsafe)
14+
# - matlab-parallel (Version: 2.1, Owner: tacc)
15+
# - matlab-desktop (Version: 1.5, Owner: designsafe)
16+
17+
ds.apps.find("opensees")
18+
ds.apps.find("mpm")
19+
20+
# All apps (quiet mode)
21+
all_apps = ds.apps.find("", verbose=False)
22+
len(all_apps)
23+
```
24+
25+
The search uses partial matching — `"matlab"` matches any app with "matlab" in the ID.
26+
27+
You can filter by ownership:
28+
29+
```python
30+
# Only apps you own
31+
ds.apps.find("", list_type="OWNED")
32+
33+
# Only shared/public apps
34+
ds.apps.find("", list_type="SHARED_PUBLIC")
35+
```
36+
37+
Valid `list_type` values: `"ALL"` (default), `"OWNED"`, `"SHARED_PUBLIC"`, `"SHARED_DIRECT"`, `"READ_PERM"`, `"MINE"`.
38+
39+
## App details
40+
41+
```python
42+
app = ds.apps.get_details("mpm-s3")
43+
# App Details:
44+
# ID: mpm-s3
45+
# Version: 0.1.0
46+
# Owner: designsafe
47+
# Execution System: frontera
48+
# Description: ...
49+
```
50+
51+
Access job configuration:
52+
53+
```python
54+
attrs = app.jobAttributes
55+
print(attrs.execSystemId) # frontera
56+
print(attrs.maxMinutes) # 2880
57+
print(attrs.coresPerNode) # 56
58+
print(attrs.execSystemLogicalQueue) # normal
59+
```
60+
61+
Request a specific version:
62+
63+
```python
64+
app = ds.apps.get_details("mpm-s3", app_version="0.1.0")
65+
```
66+
67+
Returns `None` if the app doesn't exist (instead of raising).
68+
69+
## Common apps
70+
71+
| App ID | Description |
72+
|---|---|
73+
| `designsafe-agnostic-app` | General-purpose Python, OpenSees, PyLauncher |
74+
| `matlab-r2023a` | MATLAB |
75+
| `opensees-express` | OpenSees (serial) |
76+
| `opensees-mp-s3` | OpenSees (MPI parallel) |
77+
| `mpm-s3` | Material Point Method |
78+
| `adcirc-v55` | ADCIRC coastal modeling |
79+
| `ls-dyna` | LS-DYNA finite element |

‎docs/files.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Files
2+
3+
## Path translation
4+
5+
DesignSafe uses Tapis URIs internally (`tapis://system-id/path`). Most users work with familiar paths like `/MyData/folder/` — dapi translates between the two.
6+
7+
```python
8+
from dapi import DSClient
9+
ds = DSClient()
10+
11+
# MyData → includes your username automatically
12+
ds.files.to_uri("/MyData/analysis/input/")
13+
# tapis://designsafe.storage.default/<username>/analysis/input/
14+
15+
# Community data
16+
ds.files.to_uri("/CommunityData/some-dataset/")
17+
# tapis://designsafe.storage.community/some-dataset/
18+
19+
# Projects — looks up the Tapis system ID from the project number
20+
ds.files.to_uri("/projects/PRJ-1234/data/")
21+
# tapis://project-xxxx-xxxx-xxxx/data/
22+
23+
# Already a Tapis URI — passed through unchanged
24+
ds.files.to_uri("tapis://designsafe.storage.default/<username>/folder/")
25+
```
26+
27+
Verify a path exists before using it:
28+
29+
```python
30+
ds.files.to_uri("/MyData/analysis/input/", verify_exists=True)
31+
```
32+
33+
Reverse translation (URI back to Jupyter path):
34+
35+
```python
36+
ds.files.to_path("tapis://designsafe.storage.default/<username>/data/file.txt")
37+
# /home/jupyter/MyData/data/file.txt
38+
39+
ds.files.to_path("tapis://designsafe.storage.community/datasets/eq.csv")
40+
# /home/jupyter/CommunityData/datasets/eq.csv
41+
```
42+
43+
### Supported path formats
44+
45+
| Input path | Tapis system |
46+
|---|---|
47+
| `/MyData/...` | `designsafe.storage.default/<username>/...` |
48+
| `/home/jupyter/MyData/...` | `designsafe.storage.default/<username>/...` |
49+
| `jupyter/MyData/...` | `designsafe.storage.default/<username>/...` |
50+
| `/CommunityData/...` | `designsafe.storage.community/...` |
51+
| `/projects/PRJ-XXXX/...` | `project-<uuid>/...` (auto-discovered) |
52+
| `tapis://...` | passed through unchanged |
53+
54+
## List files
55+
56+
```python
57+
files = ds.files.list("tapis://designsafe.storage.default/<username>/analysis/")
58+
for f in files:
59+
print(f"{f.name} ({f.type}, {f.size} bytes)")
60+
```
61+
62+
Pagination:
63+
64+
```python
65+
# Get items 100-199
66+
files = ds.files.list(uri, limit=100, offset=100)
67+
```
68+
69+
## Upload
70+
71+
```python
72+
ds.files.upload(
73+
"/local/path/input.json",
74+
"tapis://designsafe.storage.default/<username>/analysis/input.json",
75+
)
76+
```
77+
78+
The local file must exist and be a regular file (not a directory). Parent directories are created on the remote system.
79+
80+
## Download
81+
82+
```python
83+
ds.files.download(
84+
"tapis://designsafe.storage.default/<username>/results/output.csv",
85+
"/local/path/output.csv",
86+
)
87+
```
88+
89+
Local parent directories are created automatically. The local path must be a file path, not a directory.

‎docs/jobs.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -490,6 +490,6 @@ if final_status == "FAILED":
490490
frontera_queues = ds.systems.queues("frontera")
491491
for queue in frontera_queues:
492492
print(f"Queue: {queue.name}")
493-
print(f"Max runtime: {queue.maxRequestedTime} minutes")
494-
print(f"Max nodes: {queue.maxNodesPerJob}")
493+
print(f"Max runtime: {queue.maxMinutes} min")
494+
print(f"Max nodes: {queue.maxNodeCount}")
495495
```

‎docs/systems.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Systems
2+
3+
## Queues
4+
5+
List available batch queues on a TACC execution system.
6+
7+
```python
8+
from dapi import DSClient
9+
10+
ds = DSClient()
11+
12+
queues = ds.systems.queues("frontera")
13+
for q in queues:
14+
print(f"{q.name}: max {q.maxNodeCount} nodes, {q.maxMinutes} min")
15+
```
16+
17+
## TMS credentials
18+
19+
dapi needs SSH credentials on TACC systems to submit jobs. `DSClient()` sets these up automatically on init. To manage them manually:
20+
21+
```python
22+
# Check
23+
ds.systems.check_credentials("frontera")
24+
# → True / False
25+
26+
# Establish (idempotent — skips if already set)
27+
ds.systems.establish_credentials("frontera")
28+
29+
# Force re-create
30+
ds.systems.establish_credentials("frontera", force=True)
31+
32+
# Revoke
33+
ds.systems.revoke_credentials("frontera")
34+
```
35+
36+
## TACC systems
37+
38+
| System | Typical use |
39+
|---|---|
40+
| `frontera` | Large-scale compute |
41+
| `stampede3` | General-purpose compute |
42+
| `ls6` | Lone Star 6 |

‎myst.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,10 @@ project:
1313
- file: docs/quickstart.md
1414
- title: User Guide
1515
children:
16+
- file: docs/apps.md
17+
- file: docs/files.md
1618
- file: docs/jobs.md
19+
- file: docs/systems.md
1720
- file: docs/database.md
1821
- title: Examples
1922
children:

0 commit comments

Comments
 (0)