# Welcome {% @storylane/embed subdomain="robbie" linkValue="eclrnyt2m14v" url="" %} Robbie is an easy-to-use, high-performance computing service that lets you run Python and other programs in the cloud without hassle or complexity. Since it is built for non-developers, you don’t need cloud, IT, or software development skills. Researchers, scientists, and students find Robbie particularly useful for their Python-based Artificial Intelligence/Machine Learning experiments that require the latest GPUs, like the NVIDIA A100 or H100. Robbie works with your existing tools so that you can get started quickly. If you like building and running experiments in Jupyter Notebooks, Robbie works on popular notebook platforms like JupyterLab, Visual Studio Code, and Google Colab. If you prefer a command line, Robbie supports a modern command-line interface with fun menus and auto-completion. #### Supported Platform and Python Virtual Environments * Mac, Linux and Windows (with some caveats — see below). * Conda and non-Conda Python virtual environments - we recommend using `mamba`and/or forcing your conda default channel to \`conda-forge\`. * Note: Windows \`conda/mamba\` support is currently `experimental`due to the platform-specific packages that are installed on the local machine (windows) that are not support on the remote machine (Linux). # Running your first Job There are several ways to run computing jobs on Robbie; let’s start by looking at the Robbie remote function in a Jupyter Notebook. Or you can jump to other ways to run jobs: [Notebook Runner](/getting-started/notebook-runner) [Notebook Magics](/running-your-experiments-on-robbie/robbie-magics) [Command Runner](/getting-started/command-runner) # Remote function - Jupyter Notebook {% @storylane/embed subdomain="robbie" linkValue="vfe7iv3shjlv" url="" %} Robbie supports remotely running Python functions on GPUs in the Robbie cloud. Users typically choose this option if they have a specific task, such as a machine learning training loop, that needs the added performance of a GPU not available on their local machine. See \`Using Robbie in Jupyter Notebooks\` for a more detailed explanation of when and how to use Robbie in your experimentation. In this example, you will create a simple Jupyter Notebook on your local machine with one Python function that runs remotely on a GPU. (You can download the example here). First, open a new notebook: ``` jupyter lab ``` Then create four new (empty) cells in the notebook. In the first cell paste: ``` !pip install robbie torch ``` This will install the Robbie and PyTorch Python packages and their dependencies on your local computer. In the second cell paste: ``` import robbie robbie.login() ``` This will you and download your API key from Robbie and install it on your local machine. In the third cell paste: ``` from robbie import remote @remote(chooser_ui=True) def your_function(): # code (Add Matplotlib here) ``` In the fourth cell paste: ``` a = your_functions() print(“a is:”, a) ``` This defines the Python function (`your_function()`) that will be run remotely in the Robbie cloud. Note that the `chooser_ui=True` argument tells Robbie to display a special UI in the notebook so that the end-user can choose the hardware to run the function. Now Save the notebook (!\[A blue and white logo Description automatically generated]\(/files/wtxZzimw5lNf6sM4lS0a) on a Mac or ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FgZqj6SvFIo3pvyVUn9el%2F1.png?alt=media) on Windows) Start by pressing the ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FsEs43eb6NFvFstYGMNHo%2F2.png?alt=media) button to run the first cell. You should see the Robbie and other packages being installed. !\[A computer screen with white text Description automatically generated]\(/files/N1USyhS6KehwpDmRfANC) Next, run the second cell by pressing the ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FFBxg2AD531aAG0HCNTH5%2F4.png?alt=media) button. If you have yet to log into Robbie, you will be prompted for your username and password. Finally, run the third cell. You should see a small GUI directly in the notebook. ![Robbie Remote Function Notebook GUI](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FL0oRnNYvborYAMeSqLbm%2F5.png?alt=media) From the `Hardware Options` dropdown menu, choose `NERC Small GPU`. This is a NVIDIA V100 GPU-based virtual instance in the Robbie cloud. Next, tick the ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FTgtySmokr036xOYxjVpB%2F6.png?alt=media) checkbox. Next, press the !\[A green and black sign with a black arrow Description automatically generated]\(/files/srK6p34dSewHBy24tkhV) button. You should then see the command program executing. !\[A screenshot of a computer program Description automatically generated]\(/files/4EiGGqiCctCnvGwgX8qm) !\[A screenshot of a computer Description automatically generated]\(/files/UG4x1ooD0pgHZ9Hm4XaN) So, what is Robbie doing here? 1. Created a new run (uniquely identified as `subtle_unicorn`) and allocated a GPU machine for your run. 2. Automatically detected your local Python dependencies (packages and versions), wrote them to a `requirements.txt` file, and sent them to the remote machine. 3. Packaged up (serialized) your function and arguments and sent it to the remote machine. 4. Vended a deep link to view the run progress, logs, and artifacts in the Robbie portal. 5. On the remote machine, Robbie installed the Python dependencies, unpackaged your function, executed it, and then returned the result to the local machine. 6. Streamed the standard out from the remote machine to your local machine, including the results of the `nvidia-smi` command. 7. Printed out the duration and cost of the job once it was complete For more examples, see [Jupyter Notebook Examples](https://github.com/Positron-Networks/robbie-examples/tree/main/notebook_runner). # Notebook Runner {% @storylane/embed subdomain="robbie" linkValue="eclrnyt2m14v" url="" %} This example shows how to run an entire Jupyter Notebook on Robbie as a long-running training job, instead of an individual function. The Notebook Runner is great for when you are done experimenting in an interactive notebook and want to execute a long-running training job that could take hours or days. To run your first notebook job on Robbie, open a command prompt and type: ``` jupyter lab ``` Create two new cells in the notebook. In the first cell paste: ``` import robbie robbie.init() ``` In the second cell paste: ``` import os os.system('nvidia-smi') ``` * The first cell imports the Robbie Python package and then initializes it. If you have not previously logged in to Robbie, you will be prompted for your username and password. * The second cell contains the Python code that will be run in the Robbie cloud. Save the notebook (!\[A blue and white logo Description automatically generated]\(/files/xgX0nqdEzOUdFebgGKw9) on a Mac or ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FTdpQqPsaU2BcJVMmMJuW%2F13.png?alt=media) on Windows) Run the first cell by pressing the ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FzbPZN1NgSSJkxkQdXWCU%2F14.png?alt=media) button. You should see a small UI directly in the notebook. ![](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FNm0DAffKvSa0RQ3xOH59%2F15.png?alt=media) Select your desired Hardware, from the dropdown and tick the `Tail the remote machine stdout` check box. Next, press the !\[A green and black sign with a black arrow Description automatically generated]\(/files/71impgG09S0VeKy3lz15) button. You should then see the command program executing. ![A screenshot of a computer program](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2F5jbNovcU8nSVIjH40KVK%2F18.png?alt=media) So, what did Robbie do? 1. Converted your notebook to a Python `.py` file and removed any notebook-specific constructs like `!` `%`, or `%%`. 2. Automatically determined the Python dependencies from the `.py` file and generated a `requirement.txt` file. 3. Selected a default GPU compute instance (`NERC Small)` in the Robbie cloud 4. Set billing for the job to your \`Personal\` funds (including free trial) 5. Create a new ‘run’ called `intermediate_macaw` 6. Copied the local workspace file, including the `.py` to the remote machine 7. Vended a deep link so you can track the progress of the run in the Robbie portal 8. Launched the run in the Robbie cloud 9. Printed out the duration and cost of the job once it was complete For more examples, see [Jupyter Notebook Examples](https://github.com/Positron-Networks/robbie-examples/tree/main/notebook_runner). # Command Runner The Robbie command runner enables users to run arbitrary UNIX/Linux shell commands on a remote high-performance computing machine, including those with GPUs. For example, the command runner can run Python scripts (e.g., python file.py), fine-tune large language models (LLMs), or perform hyper-parameter turning with tools like Weights and Biases.

Robbie runcommand --help

We will start with a simple example to show the power of the Robbie job runner. (You can download the example here) First open a command prompt on your local Mac, Windows, or Linux machine and type: ``` pip install robbie robbie login ``` The first command installs the Robbie Python package on your computer. The second command prompts you for your username and password to authenticate you with the Robbie service. Your Robbie API key will be installed on your local machine. Next, open a text editor, paste the following code, and save as `main.py` ``` vi main.py ``` ![A screen shot of a computer program](https://1748587405-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDiy0cYMRuy0fFgGnKnaV%2Fuploads%2FL9gcdR4BRUKFXeD2YIGK%2F19.png?alt=media) This is a common computer vision program ``` robbie run "pip install torch && python main.py" -–y --tail ``` This command starts a “run” on the Robbie to execute the following commands (in order): * pip install torch * python main.py You should see a banner when you execute the Robbie run command.
So, what did Robbie do? 1. Selected a default GPU compute instance (NERC Small) in the Robbie cloud 2. Set billing for the job to your \`Personal\` funds (including free trial) 3. Create a new ‘run’ called \`future\_pigeon\` 4. Copied the local workspace file, including main.py (and other files) to the remote machine 5. Vended a deep link so you can track the progress of the run in the Robbie portal 6. Launched the run in the Robbie cloud 7. Tails the standard output from the remote machine to your local machine, including the results of the `pip install torch && python main.py` commands. 8. Printed out the duration and cost of the job once it was complete In this example, we showed you how to run a simple python command, but you can explore more advanced examples here. To learn how to run your Python programs on Robbie, see [here](/getting-started/command-runner). For a detailed guide on using the features of the “Robbie” command line, see [here](/robbie-command-line-reference/robbie-login). # Introduction The following concepts and nomenclature are used throughout the documentation, examples, and the Robbie service. # User Robbie identifies users by email address. A single email address can be associated with a single Robbie account. Users sign up for the Robbie service and log in to the Robbie portal using their email address and password. Robbie supports SSO with CILogin, a popular identity provider for higher education. Currently, Robbie only supports users with email addresses ending in .gov, .edu, and .org domains. # Run A “Run” (a computing job) is Robbie's core unit of work. Robbie executes ‘runs’ that end-users submit via the Robbie Command Line Interface (CLI), Remote Function, Notebook Runner, or Notebook Magic. Each run requires a billing source (Personal or Group tokens) with a positive token balance and an Environment (what hardware to use). # Token Tokens (computing credits) are Robbie's central currency. When a user submits a Run, it consumes tokens at a rate defined by the underlying hardware capabilities (see Environments). # Group (aka Team) A Group (previously called Funding Group) in Robbie is a collection of Users who share a common goal, for example, a college course or research project. Groups make it easy for administrators, like Professors or Principal Investigators) to purchase and allocate funds (Tokens) to users and control what hardware they use for their Runs. For example, a college Professor could create a Group for one of her classes and only permit her students to use a low-end CPU for their homework assignments. Users can create a Group by inviting other users and allocating some or all of their Personal tokens to these users. A user who created a Group is by default assumes the Group Administrator role and can add/delete Users, allocate funds, and further fund the group. # Environments Robbie uses “Environment” to encapsulate computing hardware combinations to reduce complexity and ease administration. An environment is comprised of: * GPU type (e.g. A10, A100, H100) * Number of virtual CPU cores * GBs of System Ram * GBs of Disk Space Robbie offers pre-defined *small*, *medium*, and *large* ‘size’ environments that users can select for their runs. Each environment consumes tokens at a different rate (per hour). The Robbie portal shows per-environment token consumption rates. Advanced users can customize environments for their specific needs. Robbie keeps track of the Environment you choose for their runs and reports utilization. ### # Workspace Robbie defines the Workspace as the directory and contents on the local machine, that will be transferred to the remote machine before the run starts. This can include files like: * Python .py * Requirements.txt * Data files Each project you work on will have its own Workspace. There is a 500 MB transfer limit for workspace uploads. As a best practice, users should not place large files (e.g., datasets) in the workspace directory but download them on the remote machine. # Dependencies Dependencies are the Python dependencies required need for a Robbie run. Dependencies are defined in a requirements.txt file. When using the Robbie Command, you can pass the ***–-autodep*** argument, and Robbie will automatically generate a requirements.txt file of Python dependencies by analyzing the .py files in the Workspace directory. # Job Configuration File Job-specific configuration parameters are stored in the `job_config.yaml` file in your workspace directory. The Robbie Python SDK, by default, reads the `job_conf.yaml` file in the current working directory to determine the funding\_group\_id, environment\_id, and image in the following cases: * `robbie run` (without –i option) * `robbie run [commands]` - if the `job_config.yaml` file contains commands, the \[commands] will be used instead. * Notebook Runner * Remote Function runs You can use the `robbie config` command or the `robbie run` command with the –i option to generate and write a `job_config.yaml` file. You can choose any name as long as it ends with .yaml. To use job configuration files with alternate names, pass the `--f` option with the filename to the `robbie run` command or when calling a remote function. Here’s an example `job_config.yaml` file: ``` version: 1.1 python_job: job_type: BASH_COMMAND_RUNNER mode: generic funding_group_id: cecfc347-5680-4fb0-ae99-b029941b08dd environment_id: 52dbdaa5-eb8e-4a3d-9745-77db52b91b34 image: auto-select include_local_dir: true ``` The parameters are defined as follows: * **job\_type:** This is the type of job, either: * `BASH_COMMAND_RUNNER` for jobs launched from the command line * `REMOTE_FUNCTION_CALL` for Python remote functions. * **mode:** This is Python mode of operation. * BASH\_COMMAND\_RUNNER - Can be one of: * `generic`- For launching generic, non-python related jobs on the remote machine. * `python`-For launching non-conda Python jobs on the remote machine. * `conda`- For launching jobs in a mamba/conda environment on the remote machine. * REMOTE\_FUNCTION\_CALL * `python`-For launching non-conda Python remote functions on the remote machine. * `conda`- For launching remote functions in a mamba/conda environment on the remote machine. * **funding\_group\_id** - String that contains the UUID of the funding group that the job will be billed against. For example, “cecfc347-5680-4fb0-ae99-b000941b08dd” * **environment\_id** - String that contains the UUID of the environment that the job will use. For example, “d26d6431-f1a5-4cea-b929-a4ed1f70eaaa” * **image** - String that contains the image name or “auto-select”. By specifying “auto-select” Robbie will choose the correct image for you. * **customer\_file\_filter** - A list of glob-style patterns to exclude. See * **commands** – These are the Linux shell commands to be run. * **env** – Environment variables and values (in key: value format) to be transferred to the remote machine and made available in the remote environment. If a value is not specified (key: ), the local environment variable will be read and sent to the remote machine. Before you run starts, you can view these parameters in the Run configuration banner: # Robbie Persistent Disk Robbie CLI commands allow you to manipulate files in the user's `persistent-disk` before or after you run a job. The `persistent-disk` will be automatically mounted at `/home/job-user/persistent-disk` on the remote machine when you run a job. Supported commands: * `ls` - list files and folders * `cp` - copy files to and from the local machine to the `persistent-disk` or between locations on the `persistent-disk` * `mv` - move files to and from the local machine to the `persistent-disk` or between locations on the `persistent-disk` * `mkdir` - create directories/folders on the `persistent-disk`. * `rm` - remove files or folders on the `persistent-disk` ### Differences with corresponding Unix/Linux commands While these commands may look similar to Unix/Linux there are differences in the syntax and behavior. Where there are behavior differences, it will be noted as a reference. Additionally, the Robbie CLI does not have the concept of a current working directory (e.g.\``` cd` `` command) on the `persistent-disk` All commands that reference (using `pd://`) the `persistent-disk` files and folders require absolute path names. Relative paths are not supported. When running these commands, you identify files and folders on the persistent disk using the `pd://` prefix. Files or folders without the `pd://`prefix are assumed to be on your local machine and DO support absolute and relative path names. ### Underlying implementation The current `persistent-disk` is implemented on top of Amazon S3. The Robbie CLI commands are meant to hide the complexity of S3 and implement permissions so users can only view their files. In terms of the Robbie system, your persistent disk will be located at: `s3://positron-dev-workspaces/{email}/persistent-job-disk`. All commands automatically insert the correct s3 path into commands such that the `persistent-disk` root (s3://) is always: `s3://positron-dev-workspaces/{email}/persistent-job-disk` ### List files/folders #### List all files/folders in root directory ```sh robbie pd ls ``` You should see all files and folders in the user's `/home/job-user/persistent-disk` directory. Names denoted with a `PRE` are folders. #### List all files/folders in the `test` directory (note the following "/", that is required) ```sh robbie pd ls pd://test/ ``` #### List all files/folders in the `test` directory and below recursively (note the following "/", that is required) ```sh robbie pd ls pd://test/ --recursive ``` #### List all files/folders in that match the *pattern* `test` directory (note there is no "/") ```sh robbie pd ls pd://test ``` #### Try to list a non-existing folder ```sh robbie pd ls pd://xyz ``` Expected Result: Nothing will be displayed ### Folders #### Create a folder ```sh robbie pd mkdir pd://test ``` You should see something like this: { "ETag": ""d41d8cd98f00b204e9800998ecf8427e"", "ChecksumCRC32": "AAAAAA==", "ChecksumType": "FULL\_OBJECT", "ServerSideEncryption": "AES256" } If you attempt to create an existing folder, it just returns the above. ### Copying files from local machine to `persistent-disk` #### Copy a local file to the `persistent-disk` root directory ```sh robbie pd cp test12.py pd://test12.py ``` — or -- #### Copy a local file to the `persistent-disk` root directory ```sh robbie pd cp testing.py pd:// ``` #### Recursively copy a local file to the `persistent-disk` ```sh robbie pd cp myDir pd://mybucket/ --recursive ``` example, if you had a local directory called `images` filled with .jpg file, you could run `robbie pd cp ./images pd://images --recursive` and it would create the images folder on the pd and upload all the images ### Copying files from `persistent-disk` to local machine #### Copy a file in the `persistent-disk` root directory to the local CWD ```sh robbie pd cp pd://testing.py ./test456.py ``` \-- other option -- #### Copy a file in the `persistent-disk` root directory to the local CWD ```sh robbie pd cp pd://testing.py . ``` #### Recursive copy files from bucket/prefix to local machine ```sh robbie pd cp pd://mybucket . --recursive ``` #### copying files between folders ``` robbie pd cp pd://images pd://test --recursive ``` ### Moving files same semantic as `cp` #### Recursively move files between folders on `pd` ```sh robbie pd mv pd://images pd://test --recursive ``` ### Deleting files/folders #### Delete a file in a folder ```sh robbie pd rm pd://images/Abyssinian_1.jpg ``` #### Recursively removing files in a folder and the folder (equivalent to `rm -rf `) ```sh robbie pd rm pd://test --recursive ``` #### Recursively removing files in a folder and the folder (equivalent to `rm -rf `) but exclude ".mat" files ```sh robbie pd rm pd://images --recursive --exclude "*.mat" ``` # Overview The Robbie portal is a web interface that allows users and administrators to manage all aspects of the Robbie service. Users typically visit the Robbie portal to monitor the progress of their jobs, download artifacts, and purchase additional tokens. You can login to the Robbie Portal at # Main Menu and Navigation You can navigate between the various screens in the Robbie portal using the main menu. # My Profile The My Profile page enables users to manage their account parameters. On the “My Profile” page, you can: * Regenerate your API key. * Note: You can only see your API the first time you generate it. Users typically set their API key using the \`Robbie login\` command or using the Robbie.login() call in a Jupyter Notebook. * View past Payment Transaction * View past Token Allocations * Allocate Tokens to Groups that you own/created # My Resources Your My Resources page shows the Environments you can use for your Personal and Group Tokens. You can click on an individual environment and see and see what arguments you need to pass to the @remote decorator, when using Robbie remote functions and the values to store in the job\_config.yaml file. # Runs You can view your “Runs” by selecting the “My Runs” menu items under your name. Your monitor vital Run parameters, including: * Unique Name * Duration * Job Status * Tokens Consumed * Logs * Artifacts like checkpoints, files, and matplotlib images You can also terminate running jobs using the (Terminate) button. # Overview ### Overview There are several ways to run computing jobs on Robbie. Which approach works best for you depends on your existing toolset (e.g. IDE) and what you are trying to accomplish. The following table highlights when to use specific Robbie capabilities: | **Robbie Capability** | **Existing Toolset** | **When to Use** | | --------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Remote Functions | Jupyter Notebook |
  • Experiments in local Jupyter Notebook or Google Colab
  • Your notebook into cells that and that need GPUs.
| | Magics | Jupyter Notebook |
  • Experiments in local Jupyter Notebook or Google Colab
  • Your notebook into cells that and that need GPUs.
| | Notebook Runner | Jupyter Notebook |
  • Long running training jobs
  • You don’t want to adapt your Notebook to run on a SLURM cluster
| | Command Runner | Windows, Mac, or Linux Command Line |
  • You work with Python .py files and a requirement.txt files
  • You need to use training frameworks that have special commands (e.g. torch tune or torch run)
| # Command Runner The Robbie command runner enables users to run arbitrary UNIX/Linux shell commands on a remote high-performance computing machine, including those with GPUs. For example, the command runner can run Python scripts (e.g., python file.py), fine-tune large language models (LLMs), or perform hyper-parameter turning with tools like Weights and Biases. You can run simple command like: * python file.py * pip install -r requirements && python main.py * python -c ‘import os; os.getcwd()’ And even more sophisticated commands like: * tune run lora\_finetune\_single\_device --config llama3/8B\_lora\_single\_device * wandb agent sweep\_id Prerequisites: To use the Robbie Command Runner, you need to: * Place all files you need on the remote machine in a local directory * Run ***robbie run –i*** and interactively build a configuration * During the interactive setup, enter the commands to be run * If you would like to see the detailed output from the remote machine, specify the ***–tail*** option * Please note that commands run in sequence, without concern for the success for failure of the previous command. For example, if you specific three individual commands like this: * cd nowhere * python file.py The second command ‘python file.py’ will run even if the command “cd nowhere” fails. To sure that commands run only after the previous success, use the && convention. Thus: \`cd nowhere\` && \`python file.py\` # Jupyter Notebooks Jupyter Notebooks are open-source documents that can be used to create, prototype, and share computational documents. They can be used for various purposes, including data science, scientific computing, computational journalism, and machine learning. One of the biggest challenges of using Jupyter Notebooks for machine learning is related to the use of GPUs (needed to speed up machine learning computations). Unfortunately, Jupyter Notebooks reserve and hold a GPU the entire time the notebook is open, even when idle and not running Python code. Furthermore, machine learning experiments often comprise other distinct phases, such as data preparation and visualization, that do not require a GPU. These shortcomings prevent others from using the GPU, drive up GPU costs, and force administrators to restrict GPU access. Robbie solves this problem by enabling users to access high-performance GPUs in a Jupyter Notebook, whether hosted on a local machine, a non-GPU notebook server, or Google Colab. There are three ways to access GPUs via Robbie in your Jupyter Notebook: * Robbie Remote Function * Robbie Magic * Robbie Notebook Runner # Robbie Python Remote Functions Robbie uses a particular Python decorator (@remote) to designate a Python function to run remotely in the Robbie cloud. Users typically choose this option if they have a specific Python function, such as a machine learning training loop, that needs the added performance of a GPU. (Remote function examples). In many ways, Remote functions behave like regular Python functions in that you can pass arguments, return results, and receive Exceptions. However, there are some differences that you should consider: * Remote functions cannot access Python global variables. If you need to access a global variable, pass it as an argument to the function. * Only data structures supported by can be passed as arguments to and returned by remote functions. * Avoid passing large data structures to the remote function, as they will be serialized and copied to the remote machine. Large data structure will delay your function from running. To use remote functions, add the following code to the function you want to run remotely. `from robbie import remote` `@remote()` `def your_function():` `# code` You can specify arguments to the decorator as follows: * **chooser\_ui**: bool - If True, a small UI will be displayed in the user’s Jupyter Notebook allowing them to choose the parameters for their run. (Works with Jupyter Notebooks only). * **funding\_group\_id**: str - String that contains the UUID of the funding group that the job will be billed against. * **environment\_id**: str - String that contains the UUID of the environment that the job will use. * **image**: str – Name of the container image to use for the run or ‘auto-select’. If you run Python file containing a remote function from the command line, such as: ```sh % python main.py ``` you can pass the following arguments: **--f \ -** This specifies the job configuration file to use (e.g. python\_job\_config.yaml) **--tail** - Streams the stdout/stderr from Robbie back to your shell **--v** - Verbose logging # Robbie Magics {% @storylane/embed subdomain="robbie" linkValue="02yruya2zaax" url="" %} #### Robbie allows you to run all or part of your Jupyter Notebook in our cloud, depending on where you are in your Python experiment lifecycle. * It is quite common to start out coding and experimenting on your local or hosted Jupyter notebook platform that is not connected to a high-performance GPU and # Robbie Notebook Runner The Notebook Runner is great for when you are done experimenting in an interactive notebook and want to execute a long-running training job that could take hours or days. To run your first notebook job on Robbie, simply add this code to your notebook: !pip install robbie then * The first cell imports the Robbie Python package and then initializes it. If you have not previously logged in to Robbie, you will be prompted for your username and password. * The second cell contains the Python code that will be run in the Robbie cloud. Save the notebook ( on a Mac or on Windows) Run the first cell by pressing the button. You should see a small UI directly in the notebook. Select your desired Hardware, from the dropdown and tick the checkbox. Next, press the button to run your job. Things to consider/watch out for: * Ensure that your notebook is saved before running the job # Matplotlib Support # Funding Group, Environment, and Images Robbie enables users to run their workloads on GPUs in minutes without complex setup and configuration. You sign up, purchase tokens, install the Robbie Python package, and start sending your jobs. By default, Robbie will consume your Personal tokens and use your default hardware (Environment). In the case of NERC this is the “NERC Small GPU”. For example: **\`robbie run “python main.py” (without a job\_config.yaml in your local directory)\`** Before Robbie executes your run, it will display the funding source (Personal or Group), environment, and Image it plans to use – along with the Token consumption rate. You can choose to proceed or exit. Robbie gives you several options when you need to customize the Group, Environment, and Image for your runs. * Run *robbie run* with the –-i (interactive) option and choose the Group, Environment, and Image for your run. * Build a customer configuration (job\_config.yaml) using the *robbie configure* command. * Using the Robbie portal, choose a funding source, environment and image then download the job\_config.yaml to use for your runs. * (Advanced) Pass *–funding\_group\_id, --environment\_id, or --image* arguments to *robbie run*. Note: You must specify UUIDs from the *–funding\_group\_id, --environment\_id* options. These are available in the Robbie portal. Robbie treats Group, Environment, and Image precedence as follows: * *Default* 🡪 *job\_config.yaml* 🡪*CLI Argument* This means that the default value will be used first. If the value is specified in the job\_config.yaml, that will be used, and finally, if an argument is specified that will be used for the job. # robbie login ### `robbie login` **Description** Authenticates the user against the Robbie platform. The user is prompted for a username and password. The user’s API key is downloaded and stored in \~./robbie/config.yaml file. # robbie config `robbie config` **Description** Enables a user to interactively create a job configuration file (job\_config.yaml) to be used by future runs. Here is an explanation of the options. The text in parenthesis is the corresponding value in the job\_config.yaml file. Value in brackets \[] represent the default value that will be selected if you simply hit the return key. You can hit the tab key to see a menu of options. * ***Choose a job type (job\_type)***- You have two options: * **Command Runner** - This job runs Linux shell commands on the remote machine. * **Remote Function -** This job runs a function of your local Python code on the remote machine. * ***Choose an environment for the remote machine (mode)***- How to use Python on the remote machine. * **Generic** - for non-Python related jobs, for example, data processing * **Python** - Jobs running in a Python (non-conda) environment. * **Conda** - Jobs running in a Conda environment. * ***Choose Python version (rpv)***- For Python environments only. An advanced setting that gives you the option to specify the version of Python to use on the remote machine. * **local** (default) - the Python version in the current environment * **3.9-3.12** - Other Python versions * ***Choose a conda environment \[.yml/.yaml] file*** (dependencies) - For Conda environments only. Choose the conda environment file to use. * **\*.yml** - An existing environment file in the local directory. * **auto-capture** - Automatically captures the conda dependencies from the current activated conda environment. Not available is you are not running under conda. * ***Python Dependencies (***dependencies) - For Python environment only. The Python dependency file to use. * **auto-capture** - Automatically captures the Python dependencies from the current environment. * **\*.txt** - An existing requirements.txt file in the current working directory. * ***Select how to bill your job (***funding\_group\_id) - This is how your job will be billed: * **Personal tokens** - These are tokens that you purchased (or free trial). * **Funding Groups** - These are tokens from teams that you have been invited to. * ***Select your preferred hardware (***environment\_id) - You can manually choose the hardware (CPU, GPU) that you want to run your job on. The cluster and cost per hour is shown. For example, * **AWS CPU (2 Tokens/Hour)** - This is a CPU machine in AWS that costs 2 tokens per hour. * **NERC Medium GPU (7 Tokens/Hour)** - This is a GPU machine running in NERC that costs 7 tokens per hour. * ***Copy local CWD to be copied to the remote machine? (***include\_local\_dir) - Select `y`if you want the files in your local directory to be copied the remote machine. By default the following files and directories are not copied: * .python-version * .DS\_Store * \_\_pycache\_\_ * job-execution * .robbie * .ipynb\_checkpoints * venv * .pyenv * .git * .venv Advanced Options (choose `y`when asked if you want to \`Configure advanced options?\`) * ***Enter file patterns to ignore*** (custom\_file\_filter) - These are full, partial, or wildcarded names of files to ignore when copying from the local directory to the remote machine if you answered `y`to ***Copy local CWD to be copied to the remote machine?*** * ***Select your preferred image (image)*** - You can manually choose an image or have Robbie automatically select one for you. * **auto-select** - Have Robbie automatically choose the image for your job. * ***Maximum tokens (max\_tokens)*** to consume before the job is automatically terminated. * ***Max duration*** (max\_duration) in minutes before the job is automatically terminated. * ***Environment variable name (env)*** - These are the environment variables to set on the remote machine. You can specify a name and value or leave the value blank and Robbie will take the current local environment variable value and send that to the remote machine. * E***nter the commands to run on the remote machine (commands)*** - For Command runner jobs only. These are the shell commands to run on the remote machine. * ***Please enter a custom run name (name)*** - If you would like to customize the run name, alternatively Robbie can generate a unique name for you. You can then choose a name for the configuration file (job\_config.yaml is the default) and save it in your local directory. # robbie run `robbie run` **Description** Launches a robbie “run” from the command line. **Synopsis** Robbie run \[OPTIONS] \[COMMANDS] **Commands** Commands can include any Linux command(s), for example: * `“pwd”` * `“nvidia-smi”` * `“python file.py”` * `“pip install -r requirements && python main.py”` * `“python -c ‘import os; os.getcwd()’”` Even more sophisticated commands: * `“tune run lora_finetune_single_device --config llama3/8B_lora_single_device”` * `“wandb agent sweep_id”` If you do not specify Commands, Robbie will look at the \`*job\_config.yaml*\` file in the local directory for commands and execute those. **Options** **`--name`**` ``(string)` String that contains the user-defined name of the run. If you omit this option, Robbie will choose a unique name for your run. **`--f`**` ``(string)` String that contains the job configuration file in the local directory to use when running the job. **`--conda`**` ``(boolean)` Run the remote job in a conda environment. If --deps is set to auto-capture then the current active conda environment will be used. If --deps points to an existing environment.yml file that file will be used to recreate the environment on the remote machine. **`--python`**` ``(boolean)` Run the remote job in a Python environment. The --version and --deps are used to create a Python environment on the remote machine. **`--funding_group`**` ``(string)` String that contains the UUID of the funding group that the job will be billed against. For example, `“cecfc347-5680-4fb0-ae99-b000941b08dd”` **`--environment_id`**` ``(string)` String that contains the UUID of the environment that the job will use. For example, `“d26d6431-f1a5-4cea-b929-a4ed1f70eaaa”` **`--image`**` ``(string)` String that contains the image name or “auto-select”. By specifying “auto-select” Robbie will choose the correct image for you. For example, `“robbie:1.0.0-gpu-py3.10-torch2.2-ubuntu22.04-dev”` **`--deps`**` ``(string)` Name of the dependency file to use for the job. If the job is conda-based, this points to an environment .yml file, if this a python job, this points to the requirements.txt file. If you specify `auto-capture` Robbie will attempt to capture the local dependencies. **`--include-local-dir`**` ``(boolean)` Copies the contents of the local directory to the remote machine. **`--tail` -**Streams the standard out of the remote host to the local host. **`--v`** -Verbose logging **`--y`** -Automatically run the job without asking the user permission. **`--i`** -Build the job configuration interactively before you run it. **`--download `** Download the file\_name from the remote machine /results directory to the local directory. If \ is “all”, then all files in the remote /results directory are zipped and downloaded as **result.zip**. **`--path `** Download the file\_name from the remote machine to the specified directory. # Architecture
# Robbie Control Plane # Remote Machine Runtime When you start a Run, Robbie will automatically allocate and start a cloud instance with the characteristics of the Environment you chose for your run. * Persistent Storage (scratch) * /usr/