[](https://github.com/Fedelau/complax/actions/workflows/python-package.yml) [](https://github.com/federicalauria/complax/releases)  [](https://opensource.org/licenses/MIT)
Complax is a Python tool designed to position solvent molecules (provided as `.xyz` files) around a user-specified atom of another molecule, also supplied in `.xyz` format.
It was primarily developed for the microsolvation of small organic molecules, but it can also be applied to other molecular systems, for instance as a starting point for further modeling or optimization studies.
After the solvent placement, the program performs a geometry optimization using the semiempirical [xTB method](https://wires.onlinelibrary.wiley.com/doi/10.1002/wcms.1493) <sup>1</sup>.
Optionally, the user can request an evaluation of the solvation effect in terms of potential energy differences.
## Installation
### Install via PyPI
You can install COMPLAX directly from PyPI using `pip`:
```bash
pip install complax
```
### Installation from GitHub:
Manually cloning the repository:
```bash
git clone https://github.com/Fedelau/complax.git
```
Then adding the location of the Complax directory to the PYTHONPATH environment variable.
## Requirements
- Python 3.8 or higher
- External dependencies:
- `numpy`
- `ase`
- `colorama`
- `tqdm`
- `tabulate`
Tested with Python 3.11.2
All dependencies can be installed with:
```bash
pip install -r requirements.txt
```
### External software
COMPLAX interfaces with the external program [xTB](https://xtb-docs.readthedocs.io/en/latest/), which must be installed and accessible from your system’s PATH.
See https://github.com/grimme-lab/xtb for installation instructions.
xTB is developed by the Grimme group and distributed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).
## Quick Start
Example input files are provided in the `examples/` folder. (If you installed `complax` via `pip`, you can access these files by cloning the repository or downloading them directly from the [GitHub `examples` directory](https://github.com/Fedelau/complax/tree/main/examples)).
This example shows how to position 3 tetrahydrofuran molecules (`thf.xyz`) around a lithium atom in methyllithium (`meli.xyz`).
1. First, identify the indices of the atoms to be used:
- Lithium atom in `meli.xyz`: 5
- Oxygen atom in `thf.xyz`: 2
2. Then run the command:
```terminal
python3 complax.py meli.xyz thf.xyz -a 5 2 -c 3
```
3. What happens next?
- The program first generates a file called `complax_input.xyz` containing the solute with the positioned solvent molecules.
- Then, a geometry optimization is performed using xTB for each numbers of solvent molecules.
- After optimization, the final geometry is saved in the `/outplax` directory named `complax_input_{n}solvent.xtbopt.xyz`, where {n} is the number of solvent molecules, choose with `-c`.
## Commandline Usage
```terminal
python3 complax.py molecule.xyz solvent.xyz [options]
```
__Mandatory arguments:__
` -a (MOLECULE ATOM) (SOLVENT ATOM)` : Atom numbers of molecule and solvent. Format: (MOLECULE ATOM) (SOLVENT ATOM) using 1-based indexing.
` -c INT ` : Number of file2 copies to be placed around the selected atom of file1. Default is 1.
__Optional arguments:__
` -t INT ` : Target distace from ```MOLECULE ATOM```, in Ångstrom. Default is 2.0 Ångstrom.
` --alpb SOLVENT` : Analytical linearized Poisson-Boltzman (ALPB) model, available solvents on xTB are acetone, acetonitrile, aniline, benzaldehyde, benzene, ch2cl2, chcl3, cs2, dioxane, dmf, dmso, ether, ethylacetate, furane, hexandecane, hexane, methanol, nitromethane, octanol, woctanol, phenol, toluene, thf, water. [[2]](https://pubs.acs.org/doi/full/10.1021/acs.jctc.1c00471)
` --gbsa SOLVENT` : The generalized Born solvation model (GBSA) is a simplified version of ALPB. Available solvents are acetone, acetonitrile, benzene (only GFN1-xTB), CH2Cl2, CHCl3, CS2, DMF (only GFN2-xTB), DMSO, ether, H2O, methanol, n-hexane (only GFN2-xTB), THF and toluene. [[2]](https://pubs.acs.org/doi/full/10.1021/acs.jctc.1c00471)
`-p INT` : Number of parallel processes. Default=1. During the initial optimization, the program will use the specified number of parallel processes. For subsequent optimizations (one for each solvent configuration), it will automatically launch as many parallel calculations as the number of solvent molecules selected.
`-lev LEVEL` : Level of theory for the optimization. Default is --gnf2. Other options include --gfn0, --gfn1, --gfn2, --gfnff.
`-chrg INT` : Molecular charge. Default is 0.
`-u, --uhf INT` : Number of unpaired electrons. Default is 1.
`--maxtries INT` : Maximum number of attempts to place each solvent molecule without overlaps. If the desired number of solvent molecules cannot be positioned, try increasing this value. However, if placement remains difficult, it is likely due to steric hindrance between the molecules. Default is 1000.
`--solvfx` : If specified, do a evaluation of the effect of the solvation in term of potential energy among the different systems with an increasing number of solvent molecules.
## Tips and Troubleshooting
- The idea is to use a optimized geometry from a DFT calculations. COMPLAX keeps the internal geometry of both solute and solvent constraints, maintaining its original interatomic distances, and finding the best solvent molecules coordination.
- COMPLAX positions solvent molecules randomly around the selected atom, avoiding overlaps and taking into account only the distance between the chosen atoms. Sometimes the molecules may not be positioned exactly as expected. It is recommended to check the result visually to ensure it is correct.
- If the positioning is not satisfactory, it is worth running the program again to obtain a better configuration.
- **Important**: COMPLAX writes output files in the outplax folder. If you want to keep multiple results, move the files out of outplax before running a new calculation, otherwise the previous files will be overwritten and lost.
## Authors
**Federica Lauria**, University of Turin, Torino, Italy
- [@Fedelau](https://github.com/Fedelau)
- [ORCID](https://orcid.org/0009-0004-0692-085X)
**Andrea Maranzana**, University of Turin, Torino, Italy
- [ORCID](https://orcid.org/0000-0002-5524-8068)
## References
[[1]](https://wires.onlinelibrary.wiley.com/doi/10.1002/wcms.1493) C. Bannwarth, E. Caldeweyher, S. Ehlert, A. Hansen, P. Pracht, J. Seibert, S. Spicher, S. Grimme WIREs Comput. Mol. Sci., 2020, 11, e01493. DOI: 10.1002/wcms.1493
[[2]](https://pubs.acs.org/doi/full/10.1021/acs.jctc.1c00471) S. Ehlert, M. Stahn, S. Spicher, S. Grimme, J. Chem. Theory Comput., 2021, 17, 4250-4261 DOI: 10.1021/acs.jctc.1c00471
## License
Complax is licensed under the [MIT](https://choosealicense.com/licenses/mit/) License.
See the [LICENSE](LICENSE) file for the full text.
Raw data
{
"_id": null,
"home_page": "https://github.com/Fedelau/complax",
"name": "complax",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "compchem, microsolvation, xtb, geometry optimization",
"author": "Federica Lauria",
"author_email": "federica.lauria95@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0b/e4/24d970362de6836697a6b009ea559f1cb98f9903acf1dfce49c183b34c91/complax-1.0.1.tar.gz",
"platform": null,
"description": " \n[](https://github.com/Fedelau/complax/actions/workflows/python-package.yml) [](https://github.com/federicalauria/complax/releases)  [](https://opensource.org/licenses/MIT) \n\nComplax is a Python tool designed to position solvent molecules (provided as `.xyz` files) around a user-specified atom of another molecule, also supplied in `.xyz` format. \nIt was primarily developed for the microsolvation of small organic molecules, but it can also be applied to other molecular systems, for instance as a starting point for further modeling or optimization studies.\n\nAfter the solvent placement, the program performs a geometry optimization using the semiempirical [xTB method](https://wires.onlinelibrary.wiley.com/doi/10.1002/wcms.1493) <sup>1</sup>. \nOptionally, the user can request an evaluation of the solvation effect in terms of potential energy differences.\n\n## Installation\n\n### Install via PyPI\n\nYou can install COMPLAX directly from PyPI using `pip`:\n\n```bash\npip install complax\n```\n\n### Installation from GitHub:\n\nManually cloning the repository:\n\n```bash\ngit clone https://github.com/Fedelau/complax.git\n```\nThen adding the location of the Complax directory to the PYTHONPATH environment variable.\n\n## Requirements\n\n- Python 3.8 or higher \n- External dependencies:\n - `numpy`\n - `ase`\n - `colorama`\n - `tqdm`\n - `tabulate`\n\nTested with Python 3.11.2\n\nAll dependencies can be installed with:\n\n```bash\npip install -r requirements.txt\n```\n### External software \n\nCOMPLAX interfaces with the external program [xTB](https://xtb-docs.readthedocs.io/en/latest/), which must be installed and accessible from your system\u2019s PATH.\nSee https://github.com/grimme-lab/xtb for installation instructions.\n\nxTB is developed by the Grimme group and distributed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).\n\n## Quick Start\n\nExample input files are provided in the `examples/` folder. (If you installed `complax` via `pip`, you can access these files by cloning the repository or downloading them directly from the [GitHub `examples` directory](https://github.com/Fedelau/complax/tree/main/examples)).\n\nThis example shows how to position 3 tetrahydrofuran molecules (`thf.xyz`) around a lithium atom in methyllithium (`meli.xyz`).\n\n1. First, identify the indices of the atoms to be used:\n - Lithium atom in `meli.xyz`: 5\n - Oxygen atom in `thf.xyz`: 2\n\n2. Then run the command:\n```terminal\npython3 complax.py meli.xyz thf.xyz -a 5 2 -c 3\n```\n3. What happens next? \n - The program first generates a file called `complax_input.xyz` containing the solute with the positioned solvent molecules.\n - Then, a geometry optimization is performed using xTB for each numbers of solvent molecules.\n - After optimization, the final geometry is saved in the `/outplax` directory named `complax_input_{n}solvent.xtbopt.xyz`, where {n} is the number of solvent molecules, choose with `-c`. \n\n## Commandline Usage\n\n```terminal\npython3 complax.py molecule.xyz solvent.xyz [options]\n```\n__Mandatory arguments:__\n\n` -a (MOLECULE ATOM) (SOLVENT ATOM)` : Atom numbers of molecule and solvent. Format: (MOLECULE ATOM) (SOLVENT ATOM) using 1-based indexing.\n\n` -c INT ` : Number of file2 copies to be placed around the selected atom of file1. Default is 1.\n\n__Optional arguments:__\n\n` -t INT ` : Target distace from ```MOLECULE ATOM```, in \u00c5ngstrom. Default is 2.0 \u00c5ngstrom.\n\n` --alpb SOLVENT` : Analytical linearized Poisson-Boltzman (ALPB) model, available solvents on xTB are acetone, acetonitrile, aniline, benzaldehyde, benzene, ch2cl2, chcl3, cs2, dioxane, dmf, dmso, ether, ethylacetate, furane, hexandecane, hexane, methanol, nitromethane, octanol, woctanol, phenol, toluene, thf, water. [[2]](https://pubs.acs.org/doi/full/10.1021/acs.jctc.1c00471)\n\n` --gbsa SOLVENT` : The generalized Born solvation model (GBSA) is a simplified version of ALPB. Available solvents are acetone, acetonitrile, benzene (only GFN1-xTB), CH2Cl2, CHCl3, CS2, DMF (only GFN2-xTB), DMSO, ether, H2O, methanol, n-hexane (only GFN2-xTB), THF and toluene. [[2]](https://pubs.acs.org/doi/full/10.1021/acs.jctc.1c00471)\n\n`-p INT` : Number of parallel processes. Default=1. During the initial optimization, the program will use the specified number of parallel processes. For subsequent optimizations (one for each solvent configuration), it will automatically launch as many parallel calculations as the number of solvent molecules selected.\n\n`-lev LEVEL` : Level of theory for the optimization. Default is --gnf2. Other options include --gfn0, --gfn1, --gfn2, --gfnff.\n\n`-chrg INT` : Molecular charge. Default is 0.\n\n`-u, --uhf INT` : Number of unpaired electrons. Default is 1.\n\n\n`--maxtries INT` : Maximum number of attempts to place each solvent molecule without overlaps. If the desired number of solvent molecules cannot be positioned, try increasing this value. However, if placement remains difficult, it is likely due to steric hindrance between the molecules. Default is 1000.\n\n`--solvfx` : If specified, do a evaluation of the effect of the solvation in term of potential energy among the different systems with an increasing number of solvent molecules.\n\n## Tips and Troubleshooting \n\n- The idea is to use a optimized geometry from a DFT calculations. COMPLAX keeps the internal geometry of both solute and solvent constraints, maintaining its original interatomic distances, and finding the best solvent molecules coordination.\n\n- COMPLAX positions solvent molecules randomly around the selected atom, avoiding overlaps and taking into account only the distance between the chosen atoms. Sometimes the molecules may not be positioned exactly as expected. It is recommended to check the result visually to ensure it is correct.\n\n- If the positioning is not satisfactory, it is worth running the program again to obtain a better configuration.\n\n- **Important**: COMPLAX writes output files in the outplax folder. If you want to keep multiple results, move the files out of outplax before running a new calculation, otherwise the previous files will be overwritten and lost.\n\n## Authors\n\n**Federica Lauria**, University of Turin, Torino, Italy \n\n\n- [@Fedelau](https://github.com/Fedelau)\n- [ORCID](https://orcid.org/0009-0004-0692-085X) \n\n**Andrea Maranzana**, University of Turin, Torino, Italy\n\n- [ORCID](https://orcid.org/0000-0002-5524-8068)\n\n## References\n\n[[1]](https://wires.onlinelibrary.wiley.com/doi/10.1002/wcms.1493) C. Bannwarth, E. Caldeweyher, S. Ehlert, A. Hansen, P. Pracht, J. Seibert, S. Spicher, S. Grimme WIREs Comput. Mol. Sci., 2020, 11, e01493. DOI: 10.1002/wcms.1493\n\n[[2]](https://pubs.acs.org/doi/full/10.1021/acs.jctc.1c00471) S. Ehlert, M. Stahn, S. Spicher, S. Grimme, J. Chem. Theory Comput., 2021, 17, 4250-4261 DOI: 10.1021/acs.jctc.1c00471\n\n## License\n\nComplax is licensed under the [MIT](https://choosealicense.com/licenses/mit/) License. \n\nSee the [LICENSE](LICENSE) file for the full text.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python tool for automatic microsolvation and geometry optimization using xTB.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Fedelau/complax"
},
"split_keywords": [
"compchem",
" microsolvation",
" xtb",
" geometry optimization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb7478f6ec5d375fe937e6304bd930b0c977f46e323788e16c7efa090c1a6224",
"md5": "b9b3e8e8c77ffba74a7af773b5a3ff8e",
"sha256": "05d50b103933cdac2bc4c7082b759832e9055fd9f3c46ca595719b9a0dc1d727"
},
"downloads": -1,
"filename": "complax-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9b3e8e8c77ffba74a7af773b5a3ff8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12226,
"upload_time": "2025-10-23T10:40:12",
"upload_time_iso_8601": "2025-10-23T10:40:12.300928Z",
"url": "https://files.pythonhosted.org/packages/eb/74/78f6ec5d375fe937e6304bd930b0c977f46e323788e16c7efa090c1a6224/complax-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0be424d970362de6836697a6b009ea559f1cb98f9903acf1dfce49c183b34c91",
"md5": "23a617fc92cc16262b92b09f88447581",
"sha256": "4e2b0c74e16ede2504e64b7462a4f576c1b1d71c30fd7d099239177a0fc491fd"
},
"downloads": -1,
"filename": "complax-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "23a617fc92cc16262b92b09f88447581",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14231,
"upload_time": "2025-10-23T10:40:13",
"upload_time_iso_8601": "2025-10-23T10:40:13.392584Z",
"url": "https://files.pythonhosted.org/packages/0b/e4/24d970362de6836697a6b009ea559f1cb98f9903acf1dfce49c183b34c91/complax-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 10:40:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Fedelau",
"github_project": "complax",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.24.2"
]
]
},
{
"name": "ase",
"specs": [
[
">=",
"3.22.1"
]
]
},
{
"name": "colorama",
"specs": [
[
">=",
"0.4.6"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.64.1"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9.0"
]
]
}
],
"lcname": "complax"
}
JSON
