Running Interactive Container Code

To run interactive container code, you'll need to go to the Code Objects page, then fill out the run details. 

Prerequisites

Create an Interactive Container code object before you complete these steps.  See this article for more details: Creating New Interactive Container Code Object.

Running Interactive Container Container Code

To do this, complete the following steps.

1. Go to the main project's page and select your project.
2. Select Code from the menu on the left to open the Code Objects page.

3. Select the Run button for the code object you'd like to run.  
4. In the Run Settings page, specify the Input Dataset(s). This is one or more Datasets to be used as input to your Code Run. If multiple Datasets are selected, each will be run separately. If a Dataset happens to be a collaborator's Dataset, the code will be run on that collaborator's Rhino Client. In other words, the data never moves outside your collaborator's Rhino Client. Note that Interactive containers require Secure Access to be enabled on the input dataset. For more information about Secure Access, please refer to What is Secure Access?
5. Add the Output Dataset Name Suffix.  A suffix that is appended to the name of each input Dataset to define the name of the output Dataset that will be created during your Code Run.
6. Indicate the Timeout in Seconds.  The number of seconds that must elapse before a Code Run is automatically killed. This is to avoid zombie tasks that run perpetually within a Rhino client. 
7. Specify the Run Parameters (Optional).  Here you can paste a JSON object that defines additional parameters to be provided to your Code Run. This can be used for specifying hyper-parameters for model validation or any parameter provided to the code. Run parameters are made available to the container code in a file located at /input/run_params.json.

NOTE:  Files that you want to run at run-time should be uploaded to the Rhino Orchestrator.  See https://docs.rhinohealth.com/hc/en-us/articles/19768490444317-How-to-use-external-files-at-run-time for more details.

To add run time files to your code run, select the run time files from the list of the workgroup run files that appears.  You will want to only include the ones you need for the code run, like in the example that follows.

Note that your workgroup run time files include both published and unpublished files.  Files from other workgroups only include the files that they have published and have made visible to you and others in your workgroup that share the same persona.  (Note that for collaborators to have access to files, they must be published.  See Managing Run Time Files to learn how to publish run time files.)

When you have completed adding all your Code Run details, either set the required compute resources by following the instruction in Setting Required Compute Resources (Autoscaling), or click the Run button to run your code.

Setting Required Compute Resources (Autoscaling)

NOTE: This feature is only available if you are running on the Google Cloud Platform (GCP).  For NVFlare code objects and code runs, you can adjust autoscaling methods for both the NVFlare Server and the NVFlare Client.  For the NVFlare Server, you can only specify the CPU and RAM. 

Autoscaling allows Rhino to run Code Runs on additional compute resources when the default Rhino Client capacity is not sufficient. This capability is designed to support resource‑intensive, "bursty"(processing tasks occur in short, intense or irregular spurts), or GPU‑based workloads while improving isolation, reliability, and cost efficiency. With autoscaling enabled, Rhino provisions temporary cloud VMs on demand, executes workloads on those VMs, and automatically terminates them when execution completes.

To help you make more efficient use of your computing resources and save on costs, you can indicate the minimum number of CPUs, amount of RAM, the disk size (VRAM), as well as the type and number of GPUs.  You can adjust these settings when you create a code object and also when you run your code.  Note that adjustments do not persist and will need to be reset with each run.

To set the required compute resources, complete the following steps.

1. In the Required Compute Resources section, move the No minimum, allow any compute requirements slider to the right. The compute resources that can be changed become visible.

2. Next, make changes to the settings as needed.  Note that these settings changes do not persist the next time you run the code object or the code run.  The settings are explained below.

3. Select Run without GPU if no GPU instance is available if your code supports CPU fallback, or if your GPU capacity is limited, but you are fine with slower results.  This option can be good if you are debugging or testing, running small datasets, or running inference for small batches.
4. Select Always create a new virtual machine allows GCP.  By default a new virtual machine is always created at runtime.  
5. When complete, click Create New Code Object or start a Code Run.

Running an iGC (Interactive Container) and Accessing Workspace Files

Interactive Containers allow you to run entire containerized applications such as Jupyter Notebook (and not just containerized code) remotely and interact with them.  You can use Jupyter Notebook, QuPath, 3D Slider, R Studio and LibreOffice.  R Studio and LibreOffice require more custom setup information: if you choose to use them, please contact us for help.

An Interactive Container similar to connecting to a remote desktop, but you do not have the ability to exfiltrate any data. (This is governed by permissions policies, requires approval from the data owner, and is logged and auditable.) 

Running an Interactive Container 

To run an iGC, complete the following steps.

1. In the Code Runs page, select a code run that has the row of type "iGC" and shows a status of "Running".
2. Connect to the active session by clicking the arrow icon.  It appears under the Type column for interactive container entries.

3. A new tab opens with the interactive session. This tab runs your Interactive Container on the remote client.
4. Click the desktop icon and interact with the application as you would normally.  

Working with Files in the Workspace Folder

In your interactive session, files such as code run outputs are stored in the /workspace folder, by default. This folder keeps your work saved across multiple interactive sessions, so you don’t have to manually save and import files as input/output datasets.  

1. If you are unfamiliar with the Rhino FCP Workspace, read Rhino FCP Workspaces. 

2. Navigate to the /workspace folder using the file explorer or navigator for your iGC platform.  If you performed a code run, results are stored, by default, in this folder.

3. If you do not want the files to be overwritten, copy them in another folder so that you can interact with them.  Note that if you overwrite a file in the /workspace folder, the changes will be in any other Interactive Container session that you have running (provided it is under your account and it is in the same workgroup).

Importing a Tabular File

There are a few ways to import a tabular file to an Interactive Container.  With the Interactive Container running: 

• Save the tabular file as /output/dataset.csv.  
• Or, after you have saved all your files, click the desktop icon named Create Output Dataset.  This will run a local script that looks for files under /output/file_data/  and populates a new /output/dataset.csv file with the file names so they can be imported as a Dataset.  

When you terminate the interactive session, the FCP will attempt to import the output Dataset defined in the /output/dataset.csv file. If you did not create this file, the Code Run will show an “Error: failure to import dataset” message.

Exporting Files from the Workspace Folder

To extract files from your /workspace folder to a location outside the Rhino Client, follow these steps:

1. Copy to Output: Within your interactive session, copy the desired files from /workspace into an output dataset directory (e.g., /output/0/file_data).

2. Import as Dataset: Import these files as a formal Rhino dataset.  For more information on how to do this, Importing to and Exporting Datasets from Your Network Storage.

3. Export to Storage: Export that dataset to client-mounted storage or to /rhino_data.  For more information on how to do this, see Importing to and Exporting Datasets from Your Network Storage.