# Resource configuration

The resource configuration (resconfig) includes all resources used in WFEngine. These are the computing resources provided by a batch system such as Slurm, the Launchpad databases (MongoDB), and runtime environments. The resconfig includes a list of workers and a default worker. The worker is mapped to the computing cluster / computer used by WFEngine. If the cluster / computer has Slurm then queues and computing resources are configured.

## Location of resource configuration file

The default location of the resource configuration is `$HOME/.fireworks/res_config.yaml`. This path can be overridden by setting the environment variable `RESCONFIG_LOC`. The actual path is returned by the function `resconfig.get_resconfig_loc()`.

## Create a resource configuration from scratch

Whether a resconfig file already exists, can be checked with this:

```python
from os import path
from virtmat.middleware.resconfig import get_resconfig_loc
path.exists(get_resconfig_loc()) # False
```

If, as in the example, a resconfig does not yet exist a new resconfig can be created and written to the default resconfig location:

```python
from virtmat.middleware.resconfig import ResConfig, set_defaults_from_guess
from virtmat.middleware.resconfig import get_resconfig_loc

cfg = ResConfig.from_scratch()
set_defaults_from_guess(cfg.default_worker)
cfg.to_file(get_resconfig_loc())
```

With this one worker configuration is created and set as default. 

## Add a worker to an existing resconfig

If a resconfig with configured workers already exists, one can add a worker for the current system:

```python
path.exists(get_resconfig_loc()) # True
cfg = ResConfig.from_file(get_resconfig_loc())
cfg.add_worker_from_scratch(default=False)
cfg.to_file(get_resconfig_loc())
```

To set the new worker as the default worker, one should call with `default=True`.

## Worker configuration

Every computer or computing cluster is represented by a worker. The worker has a name, a list of queues and a list of group names that can be used for accounting when a job is submitted to some queue. A worker configuration can be created using the `WorkerConfig` class:

```python
from virtmat.middleware.resconfig import WorkerConfig
wcfg = WorkerConfig(name='w_name')
```
In this case, the queues and the accounts have to be set manually. A more rapid method to configure a worker is to use the class method `from_scratch()`:

```python
wcfg = WorkerConfig.from_scratch()
```

In both cases, one has to set the default queue and default acount:

```python
# set the first queue as default:
wcfg.set_default_queue()
# set the current group (guid) as default:
wcfg.set_default_account()
```

One can also set a queue and a group explicitly:

```python
wcfg.default_queue = qcfg
wcfg.default_account = 'group_name'
```

If `qcfg` or `group_name` are not in the lists `queues` and `accounts`, respectively, a `ResourceConfigurationError` is raised.

The `from_scratch()` method also sets up a list of environment modules provided on the computing cluster that is accessible via the `modules` attribute.


## Queue configuration

The queue configuration accommodates computing resource configurations (attribute `resources`). Further attributes are `name`, `public`, `accounts_allow`, `accounts_deny`, and `groups_allow`. A queue configuration is created using the `QueueConfig` class:

```python
qcfg = QueueConfig()
```

With the `get_resource()` method a specific resource configuration can be retrieved:

```python
print(qcfg.get_resource('time'))
```

A resource can be set with `set_resource()` method, e.g. to set the default walltime to 5 minutes:

```python
qcfg.set_resource('time', 'default', 5)
```

If the resource does not exist, it is created and added to list of resources in the queue. The second argument, the resource type, may be one of `minimum`, `maximum` or `default`. If other keyword is used then a `ValueError` will be raised. 

With the method `validate_resource()`, a resource can be validated, e.g. to check whether time of 4000 minutes may be requested in this queue:

```python
qcfg.validate_resource('time', 4000)
```

In case the resource value exceeds the limits, then a `ResourceConfigurationError` is raised.

## Computing resource configuration

This configuration includes one single resource. The public attributes are `name`, `minimum`, `maximum` and `default`. Here an example of creating and adding a resource to the list of resources of a queue:

```python
from virtmat.middleware.resconfig import ResourceConfig 
time = ResourceConfig('time')
time.minimum = 1
time.maximum = 100
time.default = 5
qcfg.resources.append(time)
```

## Configuration of environment modules

[Environment modules](https://lmod.readthedocs.io/en/latest/) are commonly used on computing clusters to set up the run-time environment of various software. Thus they can be used as a discovery source (registry) for software deployed on the cluster. The attributes of the `ModuleConfig` class are:

* prefix (`str`): module prefix, if module name has prefix, else `None`
* name (`str`): module name, may not be `None`
* versions (`[str]`): available module versions, empty list if no versions specified
* path (`str`): path to module file, if different from default modules path, else `None`

Example: The module files `chem/gromacs/2022.6` and `chem/gromacs/2022.5` that are in the default modules path are represented in resconfig as the object `mcfg = ModuleConfig(prefix='chem', name='gromacs', versions=['2022.6', '2022.5'])`. The command `module load chem/gromacs/2022.6` can be retrieved by `mcfg.get_command('gromacs', '==2022.6')`. In case of no match, e.g. `mcfg.get_command('gromacs', '>2022.6')` will return `None`.