Command-Line Interface (CLI)

With the CONVERGE Horizon CLI, you can submit and manage jobs directly from your local file system. For advanced job monitoring, you can also access the compute instances where jobs are running.

Linux Installation

To install the CONVERGE Horizon CLI, you must have Python 3.8 or a later version installed on your system.

Open a Linux terminal and type the following command. This does not require administrative privileges:

curl -L https://gitlab.com/horizon-public/horizon-cli/-/raw/main/install_horizon.sh | bash -s

By default, the CLI is installed in $HOME/horizon. If you want to specify a different installation directory (e.g., $HOME/horizon_custom), you can do so with:

curl -L https://gitlab.com/horizon-public/horizon-cli/-/raw/main/install_horizon.sh | bash -s -- --install-dir $HOME/horizon_custom

After the installation is complete, open a new terminal or run bash to update your $PATH.

To uninstall the CLI, simply delete the installation directory (e.g., rm -rf $HOME/horizon).

You should also update your .bashrc to remove the following code snippet:

export PATH=$HOME/horizon/bin:$PATH
[[ -e "$HOME/horizon/lib/lib/python3.8/site-packages/oci_cli/bin/oci_autocomplete.sh" ]] && source "$HOME/horizon/lib/lib/python3.8/site-packages/oci_cli/bin/oci_autocomplete.sh"

Windows Installation

To install the CONVERGE Horizon CLI, you must have Python 3.8 or a later version installed on your system. To SSH to compute instances, you need Windows 10 Version 1903 or later.

First, you must enable the RemoteSigned execution policy to allow the installation script to run. Open Windows PowerShell and type:

Set-ExecutionPolicy RemoteSigned -Scope User

If you are using Windows 10 or an earlier version, force PowerShell to use TLS 1.2:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Then, type the following command to download and run the installation script. This does not require administrative privileges:

iex ((New-Object System.Net.WebClient).DownloadString('https://gitlab.com/horizon-public/horizon-cli/-/raw/main/install_horizon_windows.ps1'))

By default, the CLI is installed in C:\Users\{username}\horizon. If you want to specify a different installation directory (e.g., C:\Users\{username}\horizon_custom), download the install_horizon_windows.ps1 script from https://gitlab.com/horizon-public/horizon-cli/ and run:

install_horizon_windows.ps1 -InstallDir Users\{username}\horizon_custom

After the installation is complete, restart Windows PowerShell.

To uninstall the CLI, simply delete the installation directory (e.g., C:\Users\{username}\horizon).

You should also edit environment variables in the Control Panel to remove the path that points to C:\Users\{username}\horizon\bin.

CONVERGE Horizon Commands

After you have installed the CLI, you can use the commands listed below to submit and manage jobs on CONVERGE Horizon. The first time you type a CONVERGE Horizon command, you will be prompted to enter your CONVERGE Horizon credentials.

If you belong to multiple organizations, CONVERGE Horizon uses your default organization for the horizon job and horizon files commands. You can change your default organization with horizon config sync.

All CONVERGE Horizon commands support the --help option in addition to the options documented below.

horizon config sync

Update and sync authentication data and other settings (stored in $HOME/.oci/config) with the CONVERGE Horizon server. If you belong to multiple organizations, you can use this command to change your default organization.

USAGE:

horizon config sync

horizon files bulk-download

Download files from a given folder and subfolders in object storage to the specified DIRECTORY in your local file system. If the DIRECTORY does not exist, it will be created.

By default, all files, folders, and subfolders from your object storage home directory will be downloaded. Use the --prefix option to download a specific folder.

USAGE:

horizon files bulk-download [OPTIONS] --dest-dir DIRECTORY

OPTIONS:

--prefix TEXT

Download only the files with folder paths starting with TEXT.

--exclude TEXT

Exclude files with paths that match the pattern in TEXT. Patterns are applied relative to your home directory in object storage. Supported pattern symbols include * (matches everything), ? (matches any single character), [SEQUENCE] (matches any character in SEQUENCE), and [!SEQUENCE] (matches any character not in SEQUENCE).

--include TEXT

Include only the files with paths that match the pattern in TEXT. Patterns are applied relative to your home directory in object storage. Supported pattern symbols include * (matches everything), ? (matches any single character), [SEQUENCE] (matches any character in SEQUENCE), and [!SEQUENCE] (matches any character not in SEQUENCE).

--dry-run

List the files that will be downloaded.

--overwrite

If a file with the same name already exists in DIRECTORY, overwrite it. If neither this option nor --no-overwrite is specified, you will be prompted for each file that would be overwritten.

--no-overwrite

If a file with the same name already exists in DIRECTORY, do not overwrite it. If neither this option nor --overwrite is specified, you will be prompted for each file that would be overwritten.

EXAMPLES:

# Download flame_D.job_27 and its subfolders
horizon files bulk-download --prefix flame_D.job_27 --dest-dir downloads

# Download all files except post*.h5 files from flame_D.job_27 and its subfolders
horizon files bulk-download --prefix flame_D.job_27 --exclude *post*.h5 --dest-dir downloads

horizon files bulk-upload

Upload files from the specified DIRECTORY in your local file system to object storage.

By default, all files in DIRECTORY and its subdirectories will be uploaded to your object storage home directory. Use the --prefix option to put them in a specific folder.

USAGE:

horizon files bulk-upload [OPTIONS] --src-dir DIRECTORY

OPTIONS:

--prefix TEXT

Add TEXT prefix (i.e., folder path) to all files being uploaded.

--exclude TEXT

Exclude files with paths that match the pattern in TEXT. Patterns are applied relative to DIRECTORY. Supported pattern symbols include * (matches everything), ? (matches any single character), [SEQUENCE] (matches any character in SEQUENCE), and [!SEQUENCE] (matches any character not in SEQUENCE).

--include TEXT

Include only the files with paths that match the pattern in TEXT. Patterns are applied relative to DIRECTORY. Supported pattern symbols include * (matches everything), ? (matches any single character), [SEQUENCE] (matches any character in SEQUENCE), and [!SEQUENCE] (matches any character not in SEQUENCE).

--dry-run

List the files that will be uploaded.

--overwrite

If a file with the same name already exists in object storage, overwrite it. If neither this option nor --no-overwrite is specified, you will be prompted for each file that would be overwritten.

--no-overwrite

If a file with the same name already exists in object storage, do not overwrite it. If neither this option nor --overwrite is specified, you will be prompted for each file that would be overwritten.

EXAMPLES:

# Upload all files from for_upload directory to diesel_engine_sector folder
horizon files bulk-upload --prefix diesel_engine_sector/ --src-dir for_upload

# Upload only *.in and *.dat files from for_upload directory to diesel_engine_sector folder
horizon files bulk-upload --prefix diesel_engine_sector/ --include *.in --include *.dat --src-dir for_upload

horizon files put

Upload a specific FILE from your local file system to object storage. Specify FILE path relative to the current directory. Specify NAME in object storage relative to your object storage home directory.

USAGE:

horizon files put --file FILE --name NAME

EXAMPLE:

horizon files put --file restart.rst --name pipe_flow_cht/restart.rst

horizon job cancel

Force cancel the specified job without waiting for normal termination. Works for jobs that are pending or currently running. For currently running jobs, CONVERGE Horizon will not copy the output files back to object storage.

USAGE:

horizon job cancel JOBID

horizon job download

Download output files from object storage for the job with the specified JOBID. You must wait until the job is completed to download the output files.

By default, CONVERGE Horizon will attempt to download uncompressed files. Use the --tarball option to download compressed files.

USAGE:

horizon job download [OPTIONS] JOBID

OPTIONS:

--tarball FILE

Download the specified tar FILE (output_files.tar.lz4, restart_files.tar.lz4, or text_files.tar.lz4).

--dry-run

List the files that will be downloaded.

--output-dir, -o DIRECTORY

Download files to the specified DIRECTORY.

--include TEXT

Download only the files that match the pattern in TEXT. Patterns are applied relative to the final_output folder. Supported pattern symbols include * (matches everything), ? (matches any single character), [SEQUENCE] (matches any character in SEQUENCE), and [!SEQUENCE] (matches any character not in SEQUENCE).

--exclude TEXT

Exclude files that match the pattern in TEXT. Patterns are applied relative to the final_output folder. Supported pattern symbols include * (matches everything), ? (matches any single character), [SEQUENCE] (matches any character in SEQUENCE), and [!SEQUENCE] (matches any character not in SEQUENCE).

EXAMPLES:

# Download output_files.tar.lz4 for job 22
horizon job download --tarball output_files.tar.lz4 22

# Download all map files for job 22
horizon job download --include *map_*.h5 22

# Download boundary4-wall.out, boundary7-wall.out, and boundary8-wall.out for job 22
horizon job download --include *bound[478]-wall.out 22

horizon job scp

Copy the specified FILES from the job’s scratch directory on the compute instance to the specified DIRECTORY in your local file system. Provide FILE paths relative to the scratch directory (e.g., outputs_original/stream0/thermo.out). Provide DIRECTORY relative to the current working directory.

USAGE:

horizon job scp [OPTIONS] JOBID FILES DIRECTORY

OPTIONS:

--recursive, -r

Recursively copy subdirectories.

EXAMPLES:

# For job 906, copy all files and subdirectories in outputs_original to downloads
horizon job scp -r 906 outputs_original/* downloads

horizon job ssh

SSH to the specified job’s scratch directory on the compute instance. Works only after compute nodes have been provisioned and the job has started running.

USAGE:

horizon job ssh JOBID

horizon job status

View job status. Works only for jobs that are pending or currently running. If no JOBID is specified, CONVERGE Horizon returns all jobs that are pending or currently running for your organization.

USAGE:

horizon job status JOBID

horizon job stop

Softly stop the specified job by saving a STOP file to the Case Directory. Works only for jobs that are currently running. CONVERGE will create a restart file, finish writing output files, and end the simulation normally. CONVERGE Horizon will then copy the output files back to object storage.

USAGE:

horizon job stop JOBID

horizon job submit

For each specified PATH, upload input files to object storage and submit a job. The PATH is the path to the Case Directory on your local file system. The first time you run a given case, you will be prompted to provide information for the horizon.in file. This file is saved to the Case Directory so it can be reused for subsequent jobs.

USAGE:

horizon job submit [OPTIONS] PATHS

OPTIONS:

--interactive, -i

Submit job through browser form.

--strip DIRECTORY

Strip DIRECTORY from path in object storage.

--prompts

Regenerate horizon.in file.

When the case is uploaded, the folder path in object storage includes the directory one level above the Case Directory. For example, if you type horizon job submit /home/cases/compressor_MRF, the path in object storage will be cases/compressor_MRF. Use the --strip option if you want to remove the parent directory from the folder path in object storage (e.g., horizon job submit --strip /home/cases /home/cases/compressor_MRF).

horizon upgrade

Upgrade to the latest verison of the CONVERGE Horizon CLI.

USAGE:

horizon upgrade