Job Options#

Job options are listed here with the names that appear in the CONVERGE Horizon web interface, along with the corresponding key from the horizon.json file. Some options have slightly different names in CONVERGE Studio, and some options are not yet available in CONVERGE Studio.

Details#

Details > Job Name#

horizon.json > name

The name of the job you are running. The job will be listed with this name on the Jobs page.

Details > Associated Project#

horizon.json > project_id

The project to associate with the job.

Details > Optional Batch#

horizon.json > batch_id

The batch to which the job will be added. Leave blank if the job is not part of a batch.

You can add jobs only to your own batches (i.e., batches you created).

Details > Storage Path#

horizon.json > storage_path

The path to the directory containing the input files. This option appears only if you are using a file system for storage.

In the CONVERGE Horizon web interface, click Browse to select a directory from the file system. Paths selected in the Browse Directories modal are relative to /mnt/fs/files.

If you enter the path manually, you can provide the path relative to /mnt/fs/files or /mnt/fs, or you can provide the full path.

You can run only one job at a time from a given storage path.

CONVERGE#

CONVERGE > Version#

horizon.json > app_version

The CONVERGE version to run.

If you are running CONVERGE 2.3 or 2.4, extra steps are required as described here.

CONVERGE > License#

horizon.json > license_type

The type of license that will be used to run CONVERGE.

On-Demand:: Pay for a CONVERGE license by the job-hour based on your subscription tier (default).
Horizon-Hosted:: Use a CONVERGE license hosted on CONVERGE Horizon. This option is available only if your organization has an existing CONVERGE license agreement and has arranged for the license to be hosted on CONVERGE Horizon. If you are interested pursuing this option for a new or existing CONVERGE license, contact your Convergent Science representative.
Self-Hosted:: Use a CONVERGE license hosted on your own license server. You can use this option only if your organization has completed the Self-Hosted License Setup. If you select this option, you must specify your license server details.

CONVERGE > Time Limit#

horizon.json > time_limit_app

The maximum number of hours that CONVERGE can run before it is stopped automatically.

CONVERGE > Optional Arguments#

horizon.json > app_args

Extra command-line arguments to pass to CONVERGE. You can use this option to run chemistry utilities and other utilities for the CONVERGE solver. Your job will not incur an on-demand license charge if you use this option to run the check_inputs utility (-u check_inputs).

For a complete list of command-line options, refer to the CONVERGE Getting Started Guide and the CONVERGE Manual, available on the CONVERGE Hub (login required). Arguments for CONVERGE utilities typically have the format --utility <utility name>/-u <utility name>.

Do not use the --output-dir/-d option on CONVERGE Horizon. This option will cause your job to fail.

CONVERGE > Optional Executable Name#

horizon.json > executable

File name of a custom executable that will be used to run the job. Leave blank to run the official release of the version you selected.

Custom CONVERGE executables must be built with a compatible MPI library (as listed below) on a machine running Enterprise Linux 9 or an earlier version.

CONVERGE 5 and earlier versions: HPC-X MPI
CONVERGE 6: Intel MPI

If you specify a custom executable, it must be uploaded to the same directory as the input files. Select a CONVERGE version with the same MAJOR or MAJOR.MINOR version as the custom executable. (For example, you can select any 4.x.y version for a CONVERGE 4 executable. You can select any 3.1.x version for a CONVERGE 3.1 executable.) Note that a custom executable is required to run CONVERGE 2.3 or 2.4, as explained here.

CONVERGE > Optional Coupling#

horizon.json > coupling

To run a co-simulation in which CONVERGE is coupled to another application, select the other application here. This option requires the use of a self-hosted license for the selected application (you can still use any license type for CONVERGE).

CONVERGE > Custom License Server#

horizon.json > license_server

Port number and hostname of your CONVERGE license server, in the format 2765@hostname. This option applies only if you are using a self-hosted license for CONVERGE.

To confirm that CONVERGE Horizon is able to connect to your license server, click Test after entering the server information.

GT-SUITE#

These options appear only if you specify optional coupling with GT-SUITE.

GT-SUITE > Version#

horizon.json > coupling_version

The version of GT-SUITE to run.

GT-SUITE > Custom License Server#

horizon.json > coupling_license

Port number and hostname of your GT-SUITE license server, in the format 27005@hostname.

To confirm that CONVERGE Horizon is able to connect to your license server, click Test after entering the server information.

GT-SUITE > Optional Arguments#

horizon.json > coupling_args

Extra command-line arguments to pass to GT-SUITE.

Do not specify any of the following arguments: -v, -s, or -t. GT-SUITE might not start if these arguments are specified.

Hardware#

Hardware > Node Type#

horizon.json > node_template_id

The type of node (i.e., compute instance) that will be used to run the job. You can run jobs on bare metal (BM) servers or on virtual machines (VMs).

The availability of compute nodes at each data center fluctuates throughout the day. If your preferred node type currently has limited availability, you can still submit your job. We recommend setting a Maximum Queue Time of at least 24 hours to allow enough time for nodes to become available.

Hardware > Maximum Queue Time#

horizon.json > time_limit_queue

The maximum number of hours you are willing to wait for hardware to be allocated (allowed range: 1-168). If the requested nodes cannot be allocated within this time, the job will fail.

Hardware > Flex Cores#

horizon.json > cores_per_flex

The number of cores that will be allocated to the virtual machine. Applies only to VM node types.

Hardware > Flex Memory#

horizon.json > memory_per_flex

The amount of memory (in GB) that will be allocated to the virtual machine. Applies only to VM node types.

By default, this value increases linearly as the number of Flex Cores increases. You can override the default value as needed. Some simulations may require more memory than the default value.

Hardware > Number of Nodes#

horizon.json > nodes_count

The number of nodes to reserve for the job. Applies only to node types that allow multiple nodes per job.

In rare scenarios, it is possible for a job to run with fewer than the requested number of nodes. This occurs when a subset of the nodes that have been allocated and provisioned fail to authenticate with the cloud provider’s RoCE network (this authentication is typically the final step in the provisioning process). Instead of provisioning new nodes to replace the failed nodes—which would significantly increase the hardware cost of the job—CONVERGE Horizon will allow the job to run without the failed nodes.

Tip

Prior to September 1, 2026, you had to specify a Target Number of Nodes (horizon.json > nodes_target) and a Minimum Number of Nodes (horizon.json > nodes_min) for multi-node jobs. Those options have been replaced with a single option, Number of Nodes (horizon.json > nodes_count). If you create a job with a horizon.json file containing nodes_min and nodes_target, nodes_min will be ignored and nodes_count will be set equal to nodes_target.

Output#

Output > Output File Compression#

horizon.json > output_compress

Determines whether output files will be compressed before they are uploaded to the space. Applies only if the job files are stored in a space. By default, the output files are not compressed.

System requirements for compressed output files are described in Extract Compressed Output Files.

Output > Exclude Output#

horizon.json > output_excludes

Pattern(s) indicating which files should NOT be saved. Applies only if the job files are stored in a space. Files with paths matching the specified pattern(s) will not be uploaded to the output directory when the job is completed.

Use * to match any character in the file path. The pattern is compared to the entire file path, not just the file name. Multiple patterns can be specified as a comma-delimited list.

If you specify both this option and Include Output, included files are processed before excluded files. Leave both options blank to save all files.

Examples

*.h5
*.in,*.dat,*.cgns
*_preview*

Output > Include Output#

horizon.json > output_includes

Pattern(s) indicating which files to save. Applies only if the job files are stored in a space. Only the files with paths matching the specified pattern(s) will be uploaded to the output directory when the job is completed.

Use * to match any character in the file path. The pattern is compared to the entire file path, not just the file name. Multiple patterns can be specified as a comma-delimited list.

If you specify both this option and Exclude Output, included files are processed before excluded files. Leave both options blank to save all files.

Examples

*.out
*.out,*.h5
*outputs_*

Advanced Options#

Advanced Options > Mode#

horizon.json > interactive

The mode in which the job will run. In Automatic mode (default), CONVERGE runs automatically after the nodes are provisioned. In Interactive mode, CONVERGE is installed, but does not run automatically. You can SSH to the head node to run CONVERGE manually. Note the following:

The License option is ignored for interactive jobs. To run CONVERGE, you must complete the necessary environment setup after logging in to the head node, including the setup for connecting to your RLM license server. On-demand licensing is not available for interactive jobs.
If you run an interactive job from a space, your input and output files are not automatically copied to and from the cluster. After logging in to the head node, you can transfer files to and from the cluster with the space:download and space:upload commands.
Do not run applications that bind to ports 22, 80, or 443. These ports are used by CONVERGE Horizon.

Advanced Options > Stop If Stuck#

horizon.json > stop_if_stuck

By default, CONVERGE Horizon will automatically stop the job if it becomes stuck. A job is considered stuck if the simulation log has not been updated for over an hour, which typically indicates that the CONVERGE solver has become unresponsive and the simulation is no longer progressing.

If you do not want the job to be stopped automatically if it becomes stuck, uncheck Stop Job.

You also have the option to enable email notifications for stuck jobs, which are sent regardless of whether Stop Job is checked.

Advanced Options > Cores per Node#

horizon.json > cores_per_node

The number of cores that will be used to run the job on each node. Applies only to bare metal (BM) node types.

By default, CONVERGE Horizon uses a number of cores per node that has been optimized for the selected node type. Specify a number here only if you want to override the default value.

Advanced Options > Custom Commands to Run Instead of Default Snippet#

horizon.json > cli

The commands that will be executed instead of the default code snippet. CONVERGE Horizon runs these commands on the head node, starting in the Case Directory, and automatically redirects their standard output and standard error to horizon.log, so you should not specify output redirection. The exit code of the last command determines whether the run is reported as successful.

The environment for the selected CONVERGE version is already loaded, so mpiexec and the CONVERGE executable (converge in CONVERGE 6 and later, converge-$HORIZON_MPI in earlier versions, for example converge-hpcx) are on the PATH , and RLM_LICENSE points at the job’s license server. A lib folder in the Case Directory is on LD_LIBRARY_PATH, so shared libraries you place there are found. The horizon command-line interface on the head node is signed in as the job’s owner.

Your commands can also use any environment variable whose name starts with HORIZON_. For example, to run CONVERGE 6 on every core of every node, specify

mpiexec -np $HORIZON_CORES_TOTAL -ppn $HORIZON_CORES_PER_NODE -hostfile $HORIZON_HOSTS_FILE converge

For jobs running on multiple nodes, the default snippet also tells MPI which network to use, based on the node type. If you specify custom commands for a multi-node job, you must specify the network (e.g., with HORIZON_RDMA_DEVICE and HORIZON_RDMA_IFACE). Otherwise, MPI will pick a network on its own, which can be slower or can stop the job from starting.

Warning

Custom commands are intended only for expert users. Entering custom commands will override CONVERGE Horizon’s runtime environment, giving you complete control over what is executed on the allocated hardware. If you are not certain that the commands you entered are correct, it is likely that your job will fail. Your organization is responsible for the costs of any jobs that fail due to incorrect use of custom commands.