# Generating Localised Orbitals

`orto` can generate localised orbital `gbw` and `molden` files using `orto gen loc`.

This wraps `orca_loc` and generates cube files without the time need to write input files.

## Setup

To use this feature, you need to first set the `orto_orca_load` environment variable - this specifies the command used to load the _ORCA_ module on your system.

Typically a module system like Lmod or Environment Modules is used to manage software on HPC systems, and you will need to set this variable accordingly. 

For example, when using Environment Modules, this may be set as

```bash
    export orto_orca_load="orca/6.1.1"
```

We advise that you set this to the version of _ORCA_ you use most frequently.

Alternatively, you can provide the `--orca_load` optional argument in `orto gen loc` and specify the command to load _ORCA_ - this overrides the environment variable and so can be used to submit jobs with different versions of _ORCA_.

## Usage

To generate cube files for your canonical MOs, run

```bash
    orto gen loc <gbw_file> <method> <orb_range> [options]
```

where `<gbw_file>` is the path to your _ORCA_ `.gbw` file, `<metod>` is indicates which localisation method to use (see below), and `<orb_range>` indicates the range of orbitals to localise as two numbers separated by a hyphen.

This will then submit a batch job to generate the localised orbitals.

### Methods

All [methods](https://www.faccts.de/docs/orca/6.0/manual/contents/detailed/utilities.html#orca-loc) of `orca_loc` are available, and are referred to as

 - `fb`: Foster-Boys
 - `fb_new`: _ORCA_'s NEWBOYS Foster-Boys algorithm
 - `fb_aug`: _ORCA_'s Augmented Hessian Foster-Boys (AHFB) algorithm
 - `pm`: Pipek-Mezey
 - `iaoibo`: Knizia's original IAOIBO using PM functional
 - `iaoibo_boys`: Knizia's IAOIBO using FB functional

### Memory

The amount of memory to use in the cube file generation job can be specified using the `--memory` keyword argument, by default, 1 GB is used.

### Alpha and Beta MOs

By default, the alpha MOs will be localised.

To use beta MOs, use the `--spin beta` flag in `orto gen loc`.

### Other Arguments

Additional command line arguments for `orto gen orbs` can be listed by running 

```bash
orto gen orbs -h
```

## Example - Benzene Orbitals

From [this](benzene.gbw) file, you can use `orto` to localise the occupied canonical MOs of benzene using the IAOIBO method.

``` bash
orto gen loc benzene.gbw iaoibo 0-20
```

This creates a jobscript (`benzene_loc_job.sh`) which is then submitted to the scheduler. All output from `orca_loc` will be written to `benzene_loc.%d.o`.

After this job finishes, the files `benzene_loc.gbw ` and `benzene_loc.molden` will be present in the same directory as `benzene.gbw`.