rshub 0.3.5

This a python package to run and download submitted files on RSHub

Toolbox overview

• submit_jobs.run: submit a simulation job to the RSHub service.
• submit_jobs.check_completion: poll a job’s task status/path.
• loader = load_file.load_file: helper class to list, download, and load outputs.
• loader.list_files: list available outputs filtered by expected extension.
• loader.load_outputs: load or download outputs (auto memory/disk or forced).

RSHub client quickstart

This package lets you submit simulation jobs and fetch the resulting files from the RSHub service.

Prerequisites

• Python 3.8+ with requests, pandas, scipy, h5py, and tqdm available.

Function 1: Submit a job and job status

from rshub.submit_jobs import run, check_completion

payload = {
    "token": "YOUR_TOKEN",
    "project_name": "demo_project",
    "task_name": "snow_run_001",
    # ...other inputs expected by the backend...
}

# Fire off the job
resp = run(payload)
print("Submission response:", resp)

# Later, poll status
status = check_completion(payload["token"], payload["project_name"], payload["task_name"])
print("Task status:", status["task_status"])

• run posts your JSON payload to the service and returns the parsed JSON on success.

Function 2: Load outputs

load_file.load_file handles listing outputs, downloading files, and loading datasets.

Basic example: load one output file

from rshub.load_file import load_file

loader = load_file(
    token="YOUR_TOKEN",
    project_name="demo_project",
    task_name="snow_run_001",
    scenario_flag="snow",
    algorithm="qms",
    output_var="tb",
)

# Load and return the dataset (auto memory/disk)
data = loader.load_outputs(fGHz=16.7, inc_ang=40)
print(data.keys())  # inspect variables in the file

Full input lists

from rshub.load_file import load_file

loader = load_file(
    token="YOUR_TOKEN",
    project_name="demo_project",
    task_name="snow_run_001",
    scenario_flag="snow",      # matches output_info.csv
    algorithm="qms",
    output_var="tb",
    size_threshold_mb=50,      # switch to disk download above this size
    chunk_size=8192,           # streaming chunk size when downloading
    show_progress=True,        # show tqdm progress for large downloads
)

Constructor inputs (load_file)

• token, project_name, task_name: identify the job; required for auth/path lookup.
• scenario_flag, algorithm, output_var: select the output filename.
• (optional) size_threshold_mb: MB cutoff to switch from in-memory load to disk download. Default: 50.
• (optional) chunk_size: bytes per stream chunk when downloading large files. Default: 8192.
• (optional) show_progress: whether to display a tqdm progress bar during large downloads. Default: True

List available output files

print(loader.list_files())

Load an output file

Path1: load using frequency and incident angle

# Autodetect memory vs disk based on size; 
data = loader.load_outputs(fGHz=16.7, inc_ang=40)

• fGHz: frequency placeholder for filename patterns.
• inc_ang: incidence angle placeholder for filename patterns.

Path2: load using filename output from load_outputs

filelists = loader.list_files() 
filename=filelists[0]
data = loader.load_outputs(filename)

• filename: output filename with extension

Other optinal inputs

# Force a strategy
data_mem = loader.load_outputs(fGHz=16.7, inc_ang=40, force_method="memory")
data_disk = loader.load_outputs(fGHz=16.7, inc_ang=40, force_method="disk")

• (experimental) var: single variable or space-separated names to extract from the loaded data.
• force_method: "memory" or "disk" to override size-based strategy.
• download_path: directory path; if set, performs download-only behavior for matching files.

Download-only outputs (wildcard patterns)

loader.load_outputs(download_path="downloads/", fGHz=16.7, inc_ang=40)

• download_path: local path to download all outputs.

Download multiple specific files

loader.load_outputs(
    filename=["Passive_fGHz17.2_ob_angle0", "Passive_fGHz17.2_ob_angle40.mat"],
    download_path="downloads/"
)

• Provide a list of filenames; extensions are added if missing, partial matches are allowed with a warning, and only the matched files are downloaded.

load submitted parameters for a job

params = loader.load_parameters()
# prints project parameters

Check error messages for a job

loader.load_error_message()  # prints contents of Job/error.txt if present