# Environments

> Source: https://parallelworks.com/docs/compute/environments

# Environments

An **environment** describes where and how work can be scheduled on a cluster: a Slurm partition or PBS queue, its wall-time limits, and the scheduling fields users fill in (such as account and QoS). Users pick an environment to get a compute node for a [desktop](/docs/run/sessions/desktops), a [VS Code session](/docs/run/sessions/vscode), or a [worker](/docs/run/workers), and ACTIVATE submits the scheduler job for them.

Environments are available on cloud clusters, [managed clusters](/docs/compute/managed-clusters), and existing clusters that have a scheduler.

environment"]

    subgraph platform["ACTIVATE"]
        env["Environment<br/>partition, wall time,<br/>account, QoS, defaults"]
    end

    subgraph cluster["Cluster"]
        agent["Cluster agent"]
        sched["Slurm or PBS"]
        node["Compute node<br/>(worker)"]
    end

    user --> env
    env -->|"job request"| agent
    agent -->|"sbatch / qsub"| sched
    sched --> node
    agent -. "reports partitions<br/>and node counts" .-> env

    classDef platformNode fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
    classDef clusterNode fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#064e3b
    classDef userNode fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#4c1d95
    class env platformNode
    class agent,sched,node clusterNode
    class user userNode
    style platform stroke:#3b82f6,stroke-width:2px
    style cluster stroke:#10b981,stroke-width:2px
`} />

## Viewing environments

Open a cluster and click the **Environments** tab. The table shows each environment's **Name**, **Partition**, **Nodes** (available out of total), **Wall time** (default, with the maximum in parentheses), **Source**, and **Status**.

![Screenshot of a cluster's Environments tab listing a detected and a custom environment, with the Add button highlighted.](/content-images/docs/compute/environments/environments-tab.png?v=fc7a8554)

Anyone who can see the cluster can view its environments. Users with login access to the cluster can schedule onto its **active** environments. Adding, editing, and deleting environments requires write access to the cluster.

## Automatically detected environments

Connected clusters report their partitions to ACTIVATE, and ACTIVATE creates one environment per partition, with **Source** `auto-detected`. These stay in sync with the scheduler: node counts and wall-time limits update as the cluster reports them, and an environment whose partition disappears becomes `inactive`.

For many clusters, the detected environments are all you need. Edit one to add defaults or require an account (see [Editing an environment](#editing-an-environment)).

## Adding an environment

Add an environment yourself when you want a curated option, for example a "GPU visualization" choice with sensible defaults, on top of a partition.

1. On the **Environments** tab, click **Add**.
2. Fill in **New environment**:

   | Field | Description |
   | --- | --- |
   | **Name** | Required. Unique within the cluster. |
   | **Partition or queue** | Required. The Slurm partition or PBS queue jobs are submitted to. |
   | **Scheduler** | **SLURM** or **PBS**. |
   | **Display name** | Optional. What users see in pickers. Defaults to the name. |
   | **Description** | Optional. Shown under the name in the table. |
   | **Default wall time** | Optional. Used when a user doesn't set one. Use `HH:MM:SS`, or `D-HH:MM:SS` for multi-day limits. |
   | **Maximum wall time** | Optional. Users can't request more. Same format. |
   | **Account is required to submit** | Slurm only. Users must pick an account. |
   | **QoS is required to submit** | Slurm only. Users must pick a QoS. |

   ![Screenshot of the New environment dialog filled in for a debug partition.](/content-images/docs/compute/environments/new-environment.png?v=2bb61ff0)

3. Click **Create**. The environment reopens in edit mode so you can set its defaults.

## Editing an environment

Click **Edit** on the environment's row. You can change the display name, description, wall times, required account and QoS, and **Status** (**Active** or **Inactive**). The name, partition, and scheduler can't be changed.

Expand **Defaults and directives** to set default values for the scheduling fields. Users see defaults as placeholders and can override them; fields left blank use the default.

![Screenshot of the Edit environment dialog with Defaults and directives expanded.](/content-images/docs/compute/environments/edit-environment-defaults.png?v=ce48e5c2)

:::note
Editing a detected environment's limits, status, or defaults changes its **Source** to `custom`. ACTIVATE then stops updating it from the scheduler, and you can delete it. Changing only the display name or description keeps it detected.
:::

## Scheduling fields

These are the fields users can set when they schedule onto an environment. Desktop and VS Code sessions always request one node.

| Field | Slurm | PBS | Notes |
| --- | --- | --- | --- |
| **Number of Nodes** | ✓ | ✓ | Default 1. |
| **Number of tasks** | ✓ | | Default 1. |
| **Cores per Task** | ✓ | ✓ | Number of CPU cores to allocate per task. |
| **Wall Time** | ✓ | ✓ | Required. Can't exceed the maximum wall time. |
| **Account** | ✓ | ✓ | Slurm lists the accounts the cluster reports; shown only when accounting is enabled. PBS takes a project or allocation code. |
| **QoS** | ✓ | | Listed from the cluster; shown only when accounting is enabled. |
| **Dedicated node** | ✓ | ✓ | Reserve a whole node for this worker instead of sharing it with other jobs. On by default. |
| **Scheduler directives** | ✓ | ✓ | Extra directives, one `#SBATCH` or `#PBS` line per row. Use this for GPUs, memory, constraints, and similar options. |

For example, to request a GPU on Slurm, set **Scheduler directives** to:

```bash
#SBATCH --gpus-per-node=1
```

## Deleting an environment

Click **Delete** on a custom environment's row and confirm. Sessions and workers can no longer be scheduled with it. You can't delete an environment while workers are still using it; delete those workers first. Detected environments can't be deleted; set them to **Inactive** instead.

## From the command line

```bash
pw environments ls --cluster my-cluster
pw environments create --cluster my-cluster --name gpu-viz --partition gpu --scheduler slurm --default-time 04:00:00
pw environments update gpu-viz --cluster my-cluster --default walltime=02:00:00
```

See [`pw environments`](/docs/cli/pw/environments) for all commands.

## Troubleshooting

| Message | Cause and fix |
| --- | --- |
| _Cluster must be provisioned before creating environments_ | Start the cloud cluster first. |
| _Environment … is not active_ | The environment is **Inactive**, or its partition is no longer reported. |
| _Partition for environment … is …_ | The partition is down on the scheduler. |
| _Cannot delete this environment while … worker(s) are still using it_ | Delete those workers from [Workers](/docs/run/workers) first. |