1. Introduction

1.1. The Purpose of the SLB

The Shared License Buffer (SLB) regulates shared license usage across all HPC systems by granting and enforcing license reservations for Abaqus, ANSYS CFD, Cobalt, GASP, LS-DYNA, and STAR-CCM+.

A license reservation will be granted for a certain number of licenses, for a specific time window, and optionally, for certain licensed features of that application. Licenses cannot be checked out without a license reservation, and PBS jobs will be started only when a license reservation request has been approved.

Since licenses cannot be checked out without a reservation, users and jobs that do have a license reservation will be assured of getting their licenses throughout the entire period of their reservation.

The SLB also grants license reservations for MATLAB and Accelrys, but they are not enforced. While less robust than license reservations that are enforced, this service is nevertheless helpful because it instructs PBS to withhold a job until the licenses needed by it are available. However, PBS cannot guarantee that the licenses will still be available a few minutes later when the job actually tries to check them out. Without license enforcement there is a small chance that a job that did not request a reservation will win the race condition and acquire the licenses first. Regardless, a user is better off requesting an SLB license reservation since PBS will then know not to start the job if too few licenses are currently available. In the future, enforcement for MATLAB and/or Accelrys may be enabled based upon which policy is considered most helpful to users.

Users may access the SLB for license reservations in three ways:

1. Via PBS, by designating the needed licenses in the job script
2. Via the Advance Reservation System (ARS)
3. Interactively by running an SLB script on any HPC system

This last option is new and allows the user to make a license reservation for any time (present or future) without going through PBS or ARS. The intention is to allow users to reserve licenses for interactive work. This is described in detail later.

Another enhancement to the SLB is the capability to reserve licensed features, which is also described in further detail later.

1.2. Requesting Assistance

The HPC Help Desk is available to help users with unclassified problems, issues, or questions. Analysts are on duty 8:00 a.m - 11:00 p.m. Eastern, Monday - Friday (excluding Federal holidays).

• Web: https://helpdesk.hpc.mil
• E-mail: help@helpdesk.hpc.mil
• Phone: 1-877-222-2039 or (937) 255-0679
• Fax: (937) 656-9538

2. Using the SLB via PBS

To use shared licenses in a PBS job, all the user has to do is specify which licenses PBS needs to access. This specification is most easily done in the job script, but can be done on the qsub command line using the -l option. After doing that, the user does not need to do anything else since PBS and the SLB will internally handle the license reservation processing.

Before starting a job, PBS will make a license reservation request to the SLB based on the licenses the user requested and the job's wall-clock time. The SLB will determine whether or not enough licenses are available for the job by taking into account the job's time window (the time window is basically from the current time until the current time plus the job's wall-clock time), the number of licenses requested for the job, and all existing license reservations for the application. If sufficient licenses are available for the time window of the job, the SLB will create a license reservation for it, and the SLB will notify PBS that it can start the job. If there are not enough licenses to make a reservation for the job, then the SLB will tell PBS that it cannot start the job now and PBS will try again later.

To get the main license for an application, use one of the following:

#PBS -l abaqus=N
#PBS -l acfd_solver=1
#PBS -l MSI_TokenR=N
#PBS -l MS_castep_MP=1
#PBS -l MATLAB=1
#PBS -l cobalt=N
#PBS -l gasp=1
#PBS -l ccmppower=1 (or equivalently: #PBS -l starccm=1)
#PBS -l lsdyna=N
        

Here are samples of how to get licensed features:

#PBS -l acfd_solver=1,anshpc=N
#PBS -l MS_gulp=N
#PBS -l MATLAB=1,MATLAB_Distrib_Comp_Engine=N
#PBS -l cobalt=N,cobalt-overset=N
#PBS -l mppdyna=N
        

The SLB accommodates the following PBS shortcuts when a user specifies the licenses needed for a PBS job (not all of these shortcuts are recognized by the interactive SLB script SLB_make_resv.pl, which is discussed later).

3. Using the SLB Interactively

The SLB offers a suite of scripts ("SLB utilities") that users can interactively run to make a license reservation or cancel a reservation.

There are SLB utilities that display license reservations, display licensed features (controlled by the SLB or not), display all "reservable" features (i.e., only those that are controlled by the SLB), or obtain information about license availability.

To make a reservation interactively, a user runs the utility SLB_make_resv.pl and specifies the application, number of licenses and time window. The SLB will determine whether or not the requested number of licenses is available throughout the specified time window. If so, the license reservation request is approved and the user is notified that he/she has a license reservation. If the SLB determines that an insufficient number of licenses are available throughout the time window, the SLB will deny the license request and notify the user. The user may then make a different request, for either fewer licenses or for a different time window. The user may also reserve any licensed features that are controlled by the SLB.

If the user wants to obtain some information on license availability beforehand to make a more informed reservation request (such as through ARS), he or she can run SLB utilities to answer the following questions:

• How many licenses are available now?
• When will N licenses be available?
• How many licenses will be available at a given time?
• How many licenses will be available throughout a certain time window?
• Could a reservation for N licenses be made for a certain time window?

The last query is the same as making a reservation request except that a reservation is not made; instead, the SLB merely informs the user as to whether or not the request would have been approved or denied. And as mentioned earlier, the user can run a utility to display all reservations. All of these queries inform the users about license availability so that they may make the best license reservation(s) appropriate for their needs.

3.1. Command Line Scripts

Using the SLB interactively via the command line interface is a simple matter of picking the appropriate script and running it with the correct arguments. Some arguments are optional, some are required, and some have defaults. If a script is run with a required argument missing, it will output a "usage" message prompting the user to supply the needed argument.

The command line interface consists of the set of scripts shown below, which are available on the HPC systems. Additional information about each of the commands can be found in the sections following the chart.

Several of the scripts above have a "time window," for either making a license reservation, querying about license availability, or displaying license reservations. Each of these scripts has a default time window, but allows specification of an arbitrary time window using input arguments. A time window can be specified in any of the four following ways:

1. The start and end times can be specified in epoch time (where epoch time is the time lapse in seconds since Jan. 1, 1900) as:

   -ts epoch_start -te epoch_end

2. The start and end times can be specified in month/day_hour:minute format as:

   -st MM/DD_HH:mm -et MM/DD_HH:mm

3. The start time can be specified in epoch time as in (1) and the duration can be specified in hours as

   -ts epoch_start -dur hours

4. The start time can be specified as -st MM/DD_HH:mm as in (2) and the duration can be specified in hours as

   -st MM/DD_HH:mm -dur hours

The following section will describe the commands in Table 1 above.

3.1.1. SLB_make_resv.pl

Use SLB_make_resv.pl to request a license reservation (by policy, currently applies only to MATLAB). If the SLB approves the reservation, it will be created. Furthermore, if the reservation is to begin within 30 seconds, this script will activate the reservation before returning. Activation is the process in which the SLB directs the license manager to reserve licenses for the user. If the reservation starts more than 30 seconds into the future, the script returns immediately, as opposed to waiting for activation. In this case, activation of the interactive reservation is automatic, just as ARS reservations are.

Required inputs include application -app app and number of licenses -nlic N. A time window is also needed, and can be specified as described above with two exceptions:
(1) the duration is specified in minutes and
(2) the duration default for MATLAB is 120 (=2 hours).
Unless the default time window of 2 hours is desired, the time window must be specified. Users should specify the user with -user user_name, but if omitted the script will attempt to identify the user. Licensed features may be reserved by: -tok "feat1=N feat2=M .".

The following is an example of how to use SLB_make_resv.pl:

SLB_make_resv.pl -app matlab -nlic 1 -host hawk -user thompson -st 02/09_08:45 -et 02/09_16:00 

After making a reservation, a user should run SLB_disp_resv.pl to ensure that the reservation is correct. If not, cancel any faulty reservation by running SLB_term_resv.pl and remake the reservation with SLB_make_resv.pl.

3.1.2. SLB_term_resv.pl

This script terminates a reservation. If a reservation is not terminated explicitly (i.e., by calling SLB_term_resv.pl or by a PBS job ending), the reservation will expire at the end of its reservation window. However, by calling SLB_term_resv.pl, a reservation will be terminated and the licenses in it will be freed up sooner. The two required inputs for SLB_term_resv.pl are application -app app and ID -id ID. The SLB assigns the ID when the user creates the reservation. The user can find the ID by running SLB_disp_resv.pl.

3.1.3. SLB_all_avail.pl

This script displays license reservations. The script first displays the time window for which it will display reservations, and then displays the reservations per application (in no particular order). The easiest way to run this command is with no arguments, but input arguments can be used to specify the desired time window as described above, the type of reservations displayed (PBS, ARS, or interactive), or the application if desired.

The default time window starts at the present time and has a duration of 365 days.

If only one type of reservation is desired (type=PBS, ARS, or interactive), then it may be specified using -type J, -type A, or -type I. "J" is used for PBS "job" reservations. If no type is specified, reservations of all three types are shown.

If the user specifies an application (for example, via -app cobalt), the SLB returns the license reservations for that application. If the user does not specify an application, the default shows reservations for all applications.

3.1.4. SLB_disp_ARS_resv.pl

This script displays ARS reservations for all applications. Its time window starts at the present and has a 365-day duration.

3.1.5. SLB_disp_PBS_resv.pl

This script displays PBS reservations for all applications. Its time window starts at the present and has a 365-day duration.

3.1.6. SLB_disp_inter_resv.pl

This script displays PBS reservations for all applications. Its time window starts at the present and has a 365-day duration.

3.1.7. SLB_disp_licensed_features.pl

This script shows reservable and requestable licensed features of each SLB application. For an application, it first shows those licensed features that can be reserved, and then those that cannot be reserved through the SLB, but can be requested of PBS. A requestable feature is one that a user can request, and PBS will throttle the job based on the availability of such license, but there is no guarantee of availability and no capability to reserve it in advance. For each feature, the result shows the current number of licenses available. This script optionally accepts one application as an argument. If no argument is given, it will generate output for all supported applications.

3.1.8. SLB_disp_reservable_features.pl

This script shows the reservable features of each application and the number of licenses under the control of the SLB, which excludes licenses dedicated for groups or individuals. This script takes no arguments.

3.1.9. SLB_query_avail_block.pl

This script queries the number of licenses available for a given period (block) of time. The block of time is specifiable as described above using -st and -et, or -ts and -te. If not specified, the time period defaults to a window starting 'now' and lasting 4 hours.

3.1.10. SLB_query_avail_t.pl

This script queries the number of licenses available at a given time. The time is specifiable as described above using -st or -ts. If not specified, the time defaults to 'now'. The output shows not only how many licenses are available at the specified time, but how long after that they will remain available.

3.1.11. SLB_query_resv.pl

This script works virtually identically to SLB_make_resv.pl (described above), except it does not make a reservation. A user does not need to specify user name or host, but all other inputs are like those of SLB_make_resv.pl. Instead of making a reservation, this script gives a return code according to whether or not the requested license reservation could be made at the present time.

3.1.12. SLB_query_when.pl

This query returns the time at which the specified number of licenses will first be available and how long they will be available.

3.1.13. SLB_abaqus_map.pl

This utility computes the number of Abaqus licenses needed for an N core job. The formula it computes is P*N^0.422, where P=3 (for Foundation functionality), P=4 (for Foundation and Design or Foundation and Direct Coupling Interface), P=5 (for Standard functionality), or P=6 (for Aqua functionality). This script accepts either a single value for N -ncpu N or a range -ncpu1 N1 -ncpu2 N2.

4. Licensed Features

The new SLB controls the licenses of some (but not all) licensed features. The advantage of the SLB controlling licenses for a feature is that users may reserve the license and be assured of being able to use that feature during the reservation period.

Some licensed features come with a large number of licenses (especially many of the features of Accelrys). If there are so many licenses that we would never run out, then there is no advantage in making the feature reservable. In this case, having the SLB control the licenses to the feature burdens the user with having to make a reservation, but accomplishes nothing since the licenses would never be exhausted. Therefore, certain features are deliberately not controlled by the SLB, which allows users to use them without the need to make a reservation.

4.1. Licenses and Licensed Features

The main application licenses and licensed features controlled by the SLB are as follows:

4.2. ANSYS CFD (ACFD, formerly Fluent)

Fluent was bought by ANSYS and ANSYS changed Fluent to ACFD (Ansys CFD), and thus all Fluent licenses (fluent, fluentall, fluent_par, etc.) are obsolete. The new licenses are named acfd_solver and anshpc. A parallel job running on N cores requires one acfd_solver license and N anshpc licenses. The geographical pools used for Fluent licenses no longer apply.

4.3. Accelrys

If a user requests licenses for MS_castep_MP, MS_gulp, MS_visualizer and not enough are available, the SLB will substitute MSI_TokenR licenses, if they are available.

4.4. LS-DYNA

LS-DYNA users must reserve mppdyna for the MPPDYNA functionality and lsdyna for LSDYNA functionality.

4.5. STAR-CCM+

By policy, a user is limited to one ccmppower license at a time through ARS.