1. Qube
2. Qube! Basics

Qube! Basics

Contents

Qube! Components

There are three main components to Qube!:

1. The Worker, which is a program that runs on every computer (also called a "host") on which you want to execute your jobs.
   
   
2. The Supervisor, which runs on a dedicated machine, and keeps track of everything. It decides when a job runs, and which jobs run on which Workers.
   
   
3. The Client refers to a number of interfaces that let you run actions from the command line, stand-alone GUI, and in-application submission GUIs (e.g. from Maya, 3ds Max, Nuke, etc.). Along with the commandline and GUI, there are also APIs (application programming interfaces) for Python, Perl, and C++ that provide the means to create custom actions.
   
   1. QubeWranglerView: (WxPython) (6.4+) WranglerView  is the newly renamed Qube! GUI. This UI is aimed at advanced users, Render Wranglers and Admins.
      
   2. QubeArtistView: (PyQt) ArtistView GUI is designed to be a more artist-centric view of Qube! that delivers fast feedback on your rendering pipeline.
   3. QubeMobileView: (Python) Qube! MobileView is a light-weight webserver that serves up mobile-enhanced web pages from any machine in your facility. Note: Touch devices required for interaction . 
   4. QubeLocker: (PyQt) QBLocker gives artists the ability to control how much of their workstation is available to the render farm and shows which jobs are running on their workstation at any time.

Jobs, Instances, Agenda Items and Job Slots

A Job is what's submitted by a client to the Supervisor. It's a small bundle of information that includes all the information the Worker will need to execute the job - what program(s) to run, where the source files are, who's running it, how many CPUs it wants, what OS it can run under, all that kind of stuff. When a job is submitted to the Supervisor, it's assigned a unique jobID, that is incremented by the supervisor with each job, (e.g jobID 12345 would be assigned to the job that's submitted immediately after jobID 12344.)
When a job gets spread over multiple Workers, we say that each worker is running an Instance - even if a job is only run on one machine, that machine is running the single Instance.

Instances (or Job Processes) are numbered 0 through n, where n is the number of processes that the job can run at the same time. Therefore if one wants to have the Farm render 10 frames at a time, the number of Instances for that job should be 10. Note: Instances were called Subjobs in Qube! before version 6.4.

Agenda items (or Frames) refers to the granular list of items to be processed. Let's look at a simple example:
Job 12345 wants to render 4 frames (numbered 100-103) on two workers.
One way that might work out would be like this:

1. The (4) agenda items are: frame 100, frame 101, frame 102, and frame 103.
2. Instance 12345.0 renders frames 100 and 102 (agenda items 1 and 3)
3. Instance 12345.1 renders frames 101 and 103 (agenda items 2 and 4)

There are a lot of variations that can occur here, but the important thing to remember is the distinction between Instances and Agenda Items - Agenda Items (also commonly referred to as frames when rendering) are the granular list of things the job wants to accomplish, while Instances designate the number of machines the job is run on. (The simplest example is where the number of Instances equals the number of Agenda Items, but sometimes that's not the most efficient way to do things)

The Job Slots (or Process Slots) for a Worker determine how many processes a given Worker can run at a given time. The Job Slots have no direct relation to the number of processor cores on a given machine. It is often desirable when using a multithreaded renderer like Maya to have the Worker run 1 instance (or process) at a time. That process will in turn utilize all processor cores for the rendering. If wanting to run many single-threaded processes that require little resources, one may want to set the Worker to have 4 or 8 Job Slots available. 

Job Callbacks allow Qube! events to trigger many actions including unblocking jobs, emailing the user, or running custom scripts.

Clustering and Job Priority

 Qube! makes use of a concept it calls "clusters". The clusters in a Qube! farm are laid out in a tree-like structure, much like a directory tree where files are kept on disk. The familiar view of a directory tree is that it's "rooted" at the left, and branches out to the right.
 
Clusters are designated in the same way as a directory tree; the root is written as '/', and clusters in the root are written as /A, /B, and /C/D (/C is in the root, and D is "above" /C). Clusters are organized like a directory tree, but instead of branching left to right, it's convenient to imagine them branching upwards, away from the root. In the same way that folders in a directory tree contain files and other folders, clusters can contain other clusters. Clusters can also contain Workers and jobs. This is the key to Qube's priority scheme.

• Workers belong to 1 and only 1 cluster.
• Jobs are submitted into a cluster; you can change a job's cluster after it's submitted, but it will always be in 1 and only 1 cluster at a time.

The cluster membership of both a Worker and a job is considered when determining the overall priority of a job to run on a particular Worker. The basic rules are: 

• A Worker will run the lowest-priority job that is in its own cluster before it runs the highest-priority job from any other cluster.
• If there are no jobs in its own cluster waiting to run, a Worker will then run jobs from other cluster in decreasing priority.

So jobs from other clusters have lower priority than jobs from the same cluster. But there is even a precedence ordering for all the other clusters; jobs in clusters nearer a Worker's cluster are considered before jobs from clusters farther away. It "costs" a job priority to run in clusters other than its own, and the cost increases as the distance between the job's cluster and the Worker's cluster increases.

Climbing "down" the tree (toward the root) usually has no cost. However, a job submitted to /A/B/C has higher priority in /A/B/C, compared to /A/B, but that's just because the former case is in its own cluster. It's when a job starts climbing up the tree that it starts to lose priority.

• A job has the top cluster priority in its exact cluster path.
• It has 2nd cluster priority at all cluster nodes under its branch (towards the root).
• So, a job submitted to /A/B/C/D/E has the highest priority in /A/B/C/D/E.
• It has 2nd priority in /A/B/C/D, since a job specifically submitted to /A/B/C/D has top priority in there.

When a job cannot find any hosts by descending down its tree branch towards the root and has to start "climbing" the tree to find hosts, it loses priority. The more level it has to climb up, the lower its priority. 

• If jobA is submitted to /A, jobB to /B, then they both will have the same priority in /C.
• If jobA is submitted to /, jobB to /B, then still both of them have the same priority in /C.
• If jobA is submitted to /A, jobB to /B, jobA will have higher priority than jobB in /A/C because jobA only has to climb up 1 level, whereas jobB has to climb up 2 levels (over to / then up to /A/C).

Another example that shows how jobs in different clusters are prioritized on the same Worker in /A/B/C:

 
All jobs are first sorted by the cluster priority order for the Worker, and then sorted by the job's numerical priority value within that priority order.

• the lowest priority job with cluster priority order 1 will have a higher effective priority than the highest priority job with cluster priority order 2
• the lowest priority job with cluster priority order 2 will have a higher effective priority than the highest priority job with cluster priority order 3
• and so on…