# Polarizable Embedding

Penguin leverages the CPPE library{cite}`scheurer2019cppe` when combined with PySCF{cite}`sun2018pyscf` and PyFraMe{cite}`pyframe2021` when combined with VeloxChem{cite}`rinkevicius2020veloxchem` to compute electrostatic and polarization interactions. Polarizable Embedding (PE) is a powerful tool designed to model these interactions, making it a robust choice for embedding-based quantum chemical calculations.  
By integrating PE, Penguin ensures that users have access to state-of-the-art methods for incorporating environmental effects into their quantum chemical calculations. This capability enhances the accuracy and reliability of results for complex systems, particularly in cases where environmental interactions play a critical role.  

## How To Include PE
PE is automatically applied when the @pe section is provided and a [valid potential file](#example-potential-file) (POTFILE.pot) is given.  
The computational method is then defined as usual with the [`task`](./../general_sections/jobs.md#jobs) keyword.

## Example Input File
```
@method settings  
basis: STO-3G  
@end  

@pe  
potfile: PATH/TO/POTFILE.pot  
@end  

@memory  
max_mem: 1  
@end  

@jobs  
Task: ccs  
@end  

@molecule  
charge: 0  
multiplicity: 1  
units: bohr  
xyz:  
O  0.0000000000  0.0000000000  0.0000000000  
H  0.0000000000  1.4304281903  1.1071565216  
H  0.0000000000 -1.4304281903  1.1071565216  
@end
```

## Example Potential File
```
@environment  
units: angstrom  
xyz:  
O -1.9957202  0.0160415  1.2422556 water 1  
H -2.4542703 -0.5669741  1.8472817 water 1  
H -1.9377950 -0.4817912  0.4267562 water 1  
@end  

@charges  
O -0.67444408 water  
H  0.33722206 water  
H  0.33722206 water  
@end  

@polarizabilities  
O 5.73935090  0.00000000  0.00000000  5.73935090  0.00000000  5.73935090 water  
H 2.30839051  0.00000000  0.00000000  2.30839051  0.00000000  2.30839051 water  
H 2.30839051  0.00000000  0.00000000  2.30839051  0.00000000  2.30839051 water  
@end
```

## @pe Keywords

### General Keywords
|`potfile` <a id="potfile"></a>             |                                                                                                      |
|-------------|------------------------------------------------------------------------------------------------------|
| **Description** | Provide a relative path to the potential file. Doing so turns on PE for the specified calculation. |
| **Type**        | None                                                                                             |
| **Default**     | False                                                                                            |
| **Example**     | [An example is given here](#example-potential-file)                                               |

### CPPE Keywords

| `iso_pol` <a id="iso_pol"></a> | |
|----------------|-------------------------------------------------------------|
| **Description** | Make polarizabilities isotropic. |
| **Type**        | bool |
| **Default**     | False |

<br>

| `induced_thresh` <a id="induced_thresh"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Threshold for induced moments convergence. |
| **Type**        | float |
| **Default**     | 1.0E-8 |

<br>

| `maxiter` <a id="maxiter"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Maximum number of iterations for induced moments. |
| **Type**        | int |
| **Default**     | 50 |

<br>

| `damp_induced` <a id="damp_induced"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Enable Thole damping for induced moments. |
| **Type**        | bool |
| **Default**     | False |

<br>

| `damping_factor_induced` <a id="damping_factor_induced"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Damping factor for induced moments. |
| **Type**        | float |
| **Default**     | 2.1304 |
| **Requirements** | Requires the [`damp_induced`](#damp_induced) keyword to be True. |

<br>

| `damp_multipole` <a id="damp_multipole"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Enable Thole damping for electric fields created by multipole moments. |
| **Type**        | bool |
| **Default**     | False |

<br>

| `damping_factor_multipole` <a id="damping_factor_multipole"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Damping factor for electric fields created by multipole moments. |
| **Type**        | float |
| **Default**     | 2.1304 |
| **Requirements** | Requires the [`damp_multipole`](#damp_multipole) keyword to be True. |

<br>

| `pe_border` <a id="pe_border"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Enable border options for sites in proximity to the QM/MM border. |
| **Type**        | bool |
| **Default**     | False |

<br>

| `border_type` <a id="border_type"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Border type, either "remove" or "redist" moments/polarizabilities. |
| **Type**        | str |
| **Default**     | remove |
| **Options**     | remove<br>redist |

<br>

| `border_rmin` <a id="border_rmin"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Min radius in atomic units from QM atoms to MM sites for them to be removed/redistributed. |
| **Type**        | float |
| **Default**     | 2.2 |

<br>

| `border_nredist` <a id="border_nredist"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Number of neighbor sites to redistribute to. |
| **Type**        | int |
| **Default**     | -1 |

<br>

| `border_nredist_order` <a id="border_nredist_order"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Order from which moments are removed. |
| **Type**        | int |
| **Default**     | 1 |

<br>

| `border_redist_pol` <a id="border_redist_pol"></a> | |
|----------------|------------------------------------------------------------------|
| **Description** | Enable redistribution of polarizabilities. |
| **Type**        | bool |
| **Default**     | False |


### PyFraMe Keywords

| `threshold` <a id="threshold"></a> | |
|----------------|--------------------------------------------------------------|
| **Description** | Threshold for the induced dipoles. |
| **Type**        | float |
| **Default**     | 1.0E-8 |

<br>

| `max_iterations` <a id="max_iterations"></a> | |
|----------------|--------------------------------------------------------------|
| **Description** | Max iterations for the induced dipoles. |
| **Type**        | int |
| **Default**     | 100 |

<br>

| `solver` <a id="solver"></a> | |
|----------------|--------------------------------------------------------------|
| **Description** | Solver used to obtain the induced dipoles. |
| **Type**        | str |
| **Default**     | jacobi |
| **Options**     | jacobi<br>jidiis<br>dcji<br>dcjidiis |

<br>

| `mic` <a id="mic"></a> | |
|----------------|--------------------------------------------------------------|
| **Description** | Whether mic scaled coordinates should be used for the dipoles. |
| **Type**        | bool |
| **Default**     | False |