Using Workstations#

Follow the steps below to run CONVERGE Studio, ParaView, Tecplot, and other applications on a virtual workstation in the cloud.

Create a Workstation#

Go to Workstations and click Create Workstation. Fill out the workstation options and click Create Workstation to launch the workstation.

Note that if you plan to attach resources to the workstation, you must create the workstation in the same data center where those resources are located.

Provisioning a workstation usually takes a few minutes. When the status changes to Online, you can start using it.

View the Workstation Log#

When the workstation status is Pending, Provisioning, Online, or Deleting, you can view the workstation system log with information from the CONVERGE Horizon backend.

On the Workstations page, click on the name of the workstation to open the Workstation Details page. Expand the Log section to view the system log. Only the most recent information from the system log is displayed.

../_images/system_log2.png

An example system log for a workstation.#

Connect to a Workstation#

You can connect to a workstation once it reaches a status of Online. From the Workstations page, click on the workstation name to access the Workstation Details. In the bottom right, click Open VNC. This will open a new browser tab where you will be automatically logged in to a VNC session on the remote workstation using noVNC.

Multiple users can open the VNC session simultaneously, which allows for real-time collaboration in a shared workspace. Anyone with the VNC link (listed under Workstation Details > Connection Information) can access the workstation, even if they do not have a CONVERGE Horizon account. Take care to share the link only with trusted individuals, as the password is included in the URL.

Do not log out of the workstation with the button in the upper right. You will not be able to log back in, and the workstation will continue running until it is deleted. You can delete the workstation from CONVERGE Horizon if you are done using it.

Tip

Use the noVNC control panel if you need to copy and paste between your local machine and the remote workstation, or if you need to send a keyboard shortcut to the remote workstation. To open the control panel, click the gray tab on the left side of the workstation window.

Use your own VNC client

If you prefer to access the workstation using a VNC client installed on your machine, you can use SSH port forwarding to establish the connection. This works only if you have added an SSH key to your account.

After adding your SSH key, run the following command to open a secure connection between port 5901 on your machine and port 5901 on the workstation:

ssh -L 5901:localhost:5901 opc@SERVER_IP

Replace SERVER_IP with the IP address or DNS name from the VNC link (in the example shown below, this would be 141.148.92.60). While the SSH connection is open, you can use your local VNC client to connect to localhost:5901 with the password from the VNC link.

../_images/workstation_ip_and_password.png

If you close the SSH connection, your VNC client will lose access to the workstation.

Attach Resources to a Workstation#

You can expedite many workflows by attaching file systems or jobs to a workstation.

When you attach a file system, the file system is mounted to the workstation node. This allows you to interact with your files as though they were stored on the node itself, without having to copy files to and from the workstation. The file system remains attached until a user detaches it or until the workstation is deleted.

When you attach a job, the job’s file system is mounted to the workstation node, giving you real-time access to the results of the simulation. This option applies only to jobs created from spaces, for which results are written to scratch storage on the job cluster. (For jobs running on CONVERGE Horizon file systems, you can simply attach the file system itself, as described above—this is the same file system being used by the job.) A job remains attached to a workstation until a user detaches it or until the job is completed.

Resources can be attached to a workstation if all of the following are true:

  • The status is Online (for file systems) or Running (for jobs).

  • The resource was created in the same data center as the workstation.

  • The resource is owned by a member of your team (or your currently selected team, if you belong to more than one).

To attach a resource, go to the Workstation Details page and click Attach Resource. Select the resource to attach and click Attach. You can attach multiple resources to the same workstation.

On the workstation, run df -h in a terminal to see where the resource is mounted (look for the path /mnt/fs/files in the first column of the output). In the example below, an attached file system is mounted on /mnt/filesystem_p121uy94bayg. All of the files on the file system can be accessed at this mount point.

If you attach a job that was created from a space, it will be automatically detached from the workstation when the job is completed. To continue post-processing on the workstation, you can download the output files from the job’s output directory with the space:download command.

$ df -h
Filesystem                                          Size  Used Avail Use% Mounted on
devtmpfs                                            4.0M     0  4.0M   0% /dev
tmpfs                                               118G     0  118G   0% /dev/shm
tmpfs                                                48G   18M   48G   1% /run
/dev/mapper/ocivolume-root                           83G  6.9G   77G   9% /
/dev/sda2                                           2.0G  498M  1.5G  26% /boot
/dev/mapper/ocivolume-oled                           15G  139M   15G   1% /var/oled
/dev/sda1                                           100M  6.3M   94M   7% /boot/efi
tmpfs                                                24G   52K   24G   1% /run/user/1000
/dev/sdb                                            1.0T   17G 1007G   2% /mnt/scratch
tmpfs                                                24G   56K   24G   1% /run/user/42
10.10.168.122:/mnt/fs/files                         500G   13G  487G   3% /mnt/filesystem_p121uy94bayg
$ cd /mnt/filesystem_p121uy94bayg
$ ls
cases   geometry

Run CONVERGE Studio on a Workstation#

After connecting to a workstation, you can open a terminal to run CONVERGE Studio from the command line:

$ CONVERGE_Studio

This will open the version of CONVERGE Studio that you specified when creating the workstation. If you attached a file system to the workstation, you can navigate to the mount point to import files directly from the file system:

../_images/import_from_file_system_to_studio.png

Importing a file from an attached file system into CONVERGE Studio.#

After completing a case setup, export the files to a path on the file system:

../_images/export_to_file_system_from_studio.png

Exporting a case setup to an attached file system.#

The files will then be available to run a job. For the example shown above, the Storage Path for the job would be /cases/SI8_engine/.

If you did not attach a file system, the files you need to complete your work can be stored temporarily in the workstation storage.

Run Other Applications on a Workstation#

You can also run other applications, such as Tecplot for CONVERGE and ParaView, from the command line. Examples of commonly used commands are shown below.

# Run Tecplot for CONVERGE
$ tecplot_for_converge

# Run ParaView
$ paraview

# Run check_inputs utility
$ converge -u check_inputs

# Open Firefox browser
$ firefox

The following applications are installed on each workstation by default:

  • The bundled CONVERGE installation package, located in /mnt/fs/.cache/apps. This includes CONVERGE Studio, Tecplot for CONVERGE, and ParaView. Although the bundled installation also includes the CONVERGE solver, it cannot be used to run simulations because the solver cannot check out licenses from the workstation. You can run the converge executable only to check your input files with the -u check_inputs option.

  • The CONVERGE Horizon CLI, located at /usr/bin/horizon.

  • Tools required to compile user-defined functions (UDFs), including CMake and Make.

  • A handful of other commonly used applications, such as Firefox and gnuplot.

If you need to run an application that is not installed by default, you can install other packages with sudo dnf install. As always, be cautious when exercising sudo privileges. It is possible to lose your work if you remove a package that is required for running the workstation. You must also avoid running applications that bind to ports 22, 80, or 443, as these ports are used by CONVERGE Horizon.

Use AI Agents on a Workstation#

CONVERGE Studio 6 includes an option to activate a Model Context Protocol (MCP) server that allows CONVERGE Studio to interact with agentic coding tools such as Claude Code, Codex, and Gemini. All CONVERGE Horizon workstations have access to an AI-enabled license, so you do not need to request a license to use AI agents on CONVERGE Horizon.

A preliminary set of skills for AI agents, which contain instructions for performing basic tasks in CONVERGE Studio, are available on the Convergent Science Hub (login required). After downloading AI_CONVERGE_skills.zip and extracting the files to a folder on your computer, upload the entire skills folder to an attached file system or to the workstation storage. Then, follow these steps to complete the AI agent setup:

  1. Open a terminal on the workstation and install the CLI for the AI coding tool of your choice. Refer to the tool’s CLI installation instructions (for Linux) to find out what commands to run.

  2. Start the tool and log in to your account.

  3. Open a new terminal and run CONVERGE_Studio to open CONVERGE Studio.

  4. In Edit > Preferences > AI Agent Tools, enable AI agent tools and select the AI coding tool that you are using. Provide the path to the AI agent skills folder that you uploaded to your attached file system or workstation storage.

  5. Go to Tools > AI agent terminal to open the AI agent terminal in CONVERGE Studio.

Transfer Files To or From a Workstation#

If you specified a nonzero Storage Size when creating the workstation, your dedicated workstation storage is located in /mnt/scratch/case. You can transfer files to and from the workstation storage using one of the methods below.

After you complete your work, any files in workstation storage that you want to keep must be uploaded to a space or copied to another device before the workstation is deleted. This will happen when a user deletes the workstation or when the workstation reaches its time limit.

Upload/download files to/from a space

The CONVERGE Horizon CLI is installed on all workstations by default. You can upload/download files to/from any of your team’s spaces using the space:upload and space:download commands. Open a terminal on the workstation to run these commands (examples are shown below).

Alternatively, you can open a browser within the virtual desktop and log in to the CONVERGE Horizon web interface to upload/download files to/from your team’s spaces. Firefox is installed on all workstations by default.

# Download "output" directory from My Space to scratch storage
$ horizon space:download "My Space" "/path/to/output/" "/mnt/scratch/case"

# Upload .png files from scratch storage to "images" directory in My Space
$ horizon space:upload --include=*.png "My Space" "/path/to/images/" "/mnt/scratch/case"
Copy files using SCP/rsync

You can copy files directly to/from another device using the secure copy protocol (SCP) or the remote sync utility (rsync). The other device could be your own computer or any machine to which you have access, provided that SCP or rsync is installed and the public SSH key for the device has been added to your account. SCP is installed by default on most systems. rsync is included by default in most Linux distributions.

Example SCP and rsync commands are shown below (these examples assume that you are logged in to the other device). Remember to replace x.x.x.x with the workstation IP address or DNS name, which you can find in Workstation Details > Connection Information.

# Recursively copy files from local Case Directory to workstation scratch storage
$ scp -r /local/path/to/case [email protected]:/mnt/scratch/case

# Same as above, but using rsync instead
$ rsync -r --progress /local/path/to/case [email protected]:/mnt/scratch/case

# Recursively copy files from workstation scratch storage to local Downloads directory
$ scp -r [email protected]:/mnt/scratch/case /local/path/to/Downloads

# Same as above, but using rsync instead
$ rsync -r --progress [email protected]:/mnt/scratch/case /local/path/to/Downloads

Compile UDFs on a Workstation#

To compile user-defined functions (UDFs) on a workstation, follow the instructions in the CONVERGE UDF Manual for compiling UDFs on Linux. The CONVERGE UDF Manual is available on the Convergent Science Hub (login required).

The first step before compiling is to set up your environment using a script provided in the CONVERGE installation package. On the workstation, the CONVERGE installation root is /mnt/fs/.cache/apps and only the HPC-X package (for CONVERGE 5 and earlier versions) or the Intel MPI package (for CONVERGE 6) is installed. The exact path to the environment script depends on which version of CONVERGE is installed. Refer to the CONVERGE Getting Started Guide for details.

Delete a Workstation#

You can delete a workstation if you (and any team members sharing the workstation) are done using it.

Caution

All files in the workstation’s scratch storage will be permanently deleted. Confirm that the files you want to keep have been uploaded to a space or copied to another device before proceeding with deletion. If you are sharing the workstation with other team members, confirm that they have transferred their data as well.

To delete a workstation, go to Workstations and click on the name of the workstation to open the Workstation Details page. Click Delete in the lower right.