(allocations)=

# Allocations 

(introduction)=
## Introduction

ARC's primary mission is to facilitate breakthrough research at Virginia Tech. To this end, ARC uses an allocation system to ensure that system time is distributed in a manner appropriate to research needs while allowing faculty members and PIs the flexibility to ensure that the time allocated to a given project is managed (e.g., among graduate students) so as to maximum productivity. An allocation is a system time account requested and managed by a single person (e.g., a project PI). Many users (e.g., Co-PIs or graduate students) can then be granted access to charge against a single allocation.

Note: Allocation applications can also include requests for other resources (e.g., additional storage) required to make a project successful.

(allocation_types)=
## Allocation Types

There are two types of allocations, which differ somewhat in how they are awarded:

Research Allocations are provided for research projects and usually managed by the project's Principal Investigator (PI) (see Eligibility for Research Allocations, below). They are typically granted for a single year and can be renewed annually for the length of the project. Multi-year research allocations, such as for inclusion in a proposal submission, may be granted through negotiation with ARC.
Instructional Allocations support academic classes and are managed by the faculty member or instructor responsible for the course. Instructional allocations are typically smaller, available for shorter time periods (e.g., for the duration of the associated course), and may be limited to a select set of systems.
Eligibility for Research Allocations

Funds on ARC's systems are intended to ensure that users have the computing resources required to complete their research while also ensuring that no single user or group of users dominates the systems to the detriment of others. As such, allocations are awarded on a project-by-project basis and intended to be managed by the individual responsible for overseeing the research.

In order to manage a research project or allocation on ARC's systems, a user must fall into one of the following categories:

Be a current faculty member or post-doctoral researcher at Virginia Tech, OR
Be an employee of Virginia Tech and the Principal Investigator (PI) for a research computing-related project, OR
Be an employee of Virginia Tech and the Co-PI for a research computing-related project led by a non-Virginia Tech PI
Adjunct professors must provide a letter from their department chair, indicating that they are qualified to lead an internal research project, before their project and allocation requests can be approved.

Undergraduate and graduate students are not eligible to apply directly for projects and allocations, but must instead work under the sponsorship of a qualified researcher.

(student_eligibility)=
## Student eligibility

Undergraduate and graduate students should ask their advisor or research project PI to submit an allocation request. Once the request has been granted, they can be added to the project and submit jobs.

## Steps for getting started or setting up a new allocation

```{note}
The following steps can only be performed by someone at the pricipal investigor (PI) level at Virginia Tech, typically a VT faculty member.
```

### Create a Project
In ColdFront, a "Project" is created first and then elements like users, allocations, and pulications are added to the project. 

1. Log in to [ColdFront](https://coldfront.arc.vt.edu)
2. From the "Home" page, click `Projects >>`, and then `+Add a Project` to create a new Project
3. Fill and submit the form (Title, Description (1 paragraph), and Department)

### Add Users to a Project

By adding users to the project, they will be elligible for addition to the other project components like compute or storage allocations.
1. Log in to [ColdFront](https://coldfront.arc.vt.edu) and select the Project you want to manage
2. Click the `+Add Users` button to search and add users to the Project
3. If you already have allocations in the project, you will be given the option to also add the users to those allocation in this step.

### Add Allocations to a Project

"Allocations" are time-limited accounting objects which allow you to make use of ARC systems at scale. The two most common are "Compute (free) Cluster" and "Project (free) Storage" allocations. These are provided to PIs at no cost and represent the "Free Tier" of ARC system usage. Most people who use ARC systems operate at this level, but additional provisioning is available via the [ARC Cost Center](costcenter).

1. Log in to [ColdFront](https://coldfront.arc.vt.edu) and select the Project you want to manage
2. Click the `+Request Resource Allocation` button to add an allocation to the Project
3. Select the [allocation type](allocationtypes) you require, then fill and submit the form

```{warning}
When creating a new `Compute` type allocation, you will need to provide an account name. This is a name (Slurm account name) which will be provided every time a job is submitted. You will need to use the "Click here to create an account name!" link to create a new account name.

Account names should be all lowercase, easy to type and remember, and short. An acronym or abbreviation is usually appropriate. Avoid special characters and long names.
```
(allocationtypes)=
### Table of allocation types in ColdFront 
|name|type|description|Limits|
|-|-|-|-|
|Compute (free) Cluster|compute time on clusters|Free tier compute time|600,000 units/month per PI among all Free tier allocations|
|Compute (paid) Cluster|compute time on clusters|[ARC Cost Center](Cost-center), priority tier compute time| variable based on amount paid |
|Project (free) Storage|Group storage space|Free tier, group shared storage|25 terabytes per PI among all free tier storage|