========================
CODE SNIPPETS
========================
TITLE: OPI Configuration File Example
DESCRIPTION: Example TOML configuration file for OPI. This file specifies the absolute paths to the ORCA and Open MPI base directories, which are required for OPI to function correctly. The file should be located at `$XDG_CONFIG_HOME/opi/config.toml`.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/install.md#_snippet_2

LANGUAGE: toml
CODE:
```
ORCA_PATH = "/path/to/orca/"
# > Path to Open MPI installed with `apt`
MPI_PATH = "/usr"
```

----------------------------------------

TITLE: Install OPI in Development Mode
DESCRIPTION: Installs the OPI package in development mode, creating a virtual environment and installing necessary dependencies. Use `--only-dev` to install development dependencies, `--group <groupname>` to include specific dependency groups, or `--all-groups` to include all dependencies.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_2

LANGUAGE: Shell
CODE:
```
uv sync
uv sync --only-dev
uv sync --group <groupname>
uv sync --all-groups
```

----------------------------------------

TITLE: Nox Session Definition Example
DESCRIPTION: An example of defining a Nox session in `noxfile.py` with tags for grouping and running external commands.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_7

LANGUAGE: python
CODE:
```
@nox.session(tags=["static_check"])
def type_check(session):
    session.run_always("uv", "sync", "--group", "type_check")
    session.run("mypy")
```

----------------------------------------

TITLE: Install uv with pipx
DESCRIPTION: Installs the uv package manager using pipx, a tool for installing and running Python applications in isolated environments. This is the preferred method for setting up uv.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_0

LANGUAGE: Shell
CODE:
```
pipx install uv
```

----------------------------------------

TITLE: Import OPI and Visualization Dependencies
DESCRIPTION: Imports necessary Python modules for ORCA calculations using OPI, including core components for calculator and output handling, simple keywords, and structure definition. Also imports `py3Dmol` for visualization, noting its potential installation requirement.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/how_to_opi.ipynb#_snippet_0

LANGUAGE: python
CODE:
```
from pathlib import Path
import shutil

# > OPI imports for performing ORCA calculations and reading output
from opi.core import Calculator
from opi.output.core import Output
from opi.input.simple_keywords import Dft, Task
from opi.input.structures.structure import Structure

# > for visualization of molecules
import py3Dmol
```

----------------------------------------

TITLE: Install OPI from GitHub
DESCRIPTION: Installs the OPI Python library by cloning the source code from GitHub. This method involves setting up a virtual environment and installing the package locally, which is recommended for development or specific versions.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/install.md#_snippet_1

LANGUAGE: shell
CODE:
```
git clone https://github.com/faccts/opi.git
cd opi
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install .
```

----------------------------------------

TITLE: Run ORCA Calculation and Get Output
DESCRIPTION: Executes the ORCA calculation by first writing the input file and then calling the `run()` method on the `Calculator` object. After the calculation completes, it retrieves the results as an `Output` object.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/how_to_opi.ipynb#_snippet_4

LANGUAGE: python
CODE:
```
def run_calc(calc: Calculator) -> Output:
    # > Write the ORCA input file
    calc.write_input()
    # > Run the ORCA calculation
    print("Running ORCA calculation ...", end="")
    calc.run()
    print("   Done")

    # > Get the output object
    output = calc.get_output()
    
    return output

output = run_calc(calc)
```

----------------------------------------

TITLE: Setup ORCA Calculation Calculator
DESCRIPTION: Configures an OPI `Calculator` object for an ORCA calculation. It assigns the molecular structure, specifies the calculation level of theory (r2SCAN-3c for single point energy), and sets the number of CPU cores to use. The function returns the configured calculator instance.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/how_to_opi.ipynb#_snippet_3

LANGUAGE: python
CODE:
```
def setup_calc(basename : str, working_dir: Path, structure: Structure, ncores: int = 1) -> Calculator:
    # > Set up a Calculator object, the basename for the ORCA calculation is also set
    calc = Calculator(basename=basename, working_dir=working_dir)
    # > Assign structure to calculator
    calc.structure = structure

    # Define a level of theory: we use r2SCAN-3c for geometry optimization
    sk_list = [
        Dft.R2SCAN_3C, # > r2SCAN-3c method (Comes with a predefined basis set)
        Task.SP # > Perform the singlepoint
    ]

    # > Use simple keywords in calculator
    calc.input.add_simple_keywords(*sk_list)

    # > Define number of CPUs for the calcualtion
    calc.input.ncores = ncores # > CPUs for this ORCA run (default: 1)

    return calc

calc = setup_calc("single_point", working_dir=working_dir, structure=structure)
```

----------------------------------------

TITLE: Install OPI from PyPI
DESCRIPTION: Installs the OPI Python library directly from the Python Package Index (PyPI) using pip. This is the simplest method for obtaining the library.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/install.md#_snippet_0

LANGUAGE: shell
CODE:
```
pip install orca-pi
```

----------------------------------------

TITLE: Install openCOSMO-RS_py
DESCRIPTION: Installs the openCOSMO-RS_py library from GitHub into the OPI virtual environment. This is a prerequisite for running the tutorial.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/opencosmors.ipynb#_snippet_0

LANGUAGE: shell
CODE:
```
uv pip install git+https://github.com/TUHH-TVT/openCOSMO-RS_py
```

----------------------------------------

TITLE: Install OPI from GitHub
DESCRIPTION: Clones the OPI repository from GitHub, sets up a Python virtual environment, and installs the package locally. This method is suitable for development or obtaining the latest code.

SOURCE: https://github.com/faccts/opi/blob/main/README.md#_snippet_1

LANGUAGE: shell
CODE:
```
git clone https://github.com/faccts/opi.git
cd opi
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install .
```

----------------------------------------

TITLE: Ruff Linting and Formatting Commands
DESCRIPTION: Commands to execute Ruff for linting, sorting imports, and code formatting.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_9

LANGUAGE: shell
CODE:
```
nox -s lint
```

LANGUAGE: shell
CODE:
```
nox -s imports
```

LANGUAGE: shell
CODE:
```
nox -s format_code
```

----------------------------------------

TITLE: Accessing Final Energy
DESCRIPTION: Demonstrates how to access the final energy from the calculation results object. It retrieves the energy from the first geometry's single point data and prints it.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/how_to_opi.ipynb#_snippet_6

LANGUAGE: python
CODE:
```
# > Total energy in Hartee
Etot = output.results_properties.geometries[0].single_point_data.finalenergy

# > Print total energy
print("Final energy in Hartee: ",Etot)
```

----------------------------------------

TITLE: Define and Create Working Directory
DESCRIPTION: Sets up a dedicated subfolder named `RUN` for ORCA calculations. It ensures the directory is clean by removing it if it exists and then creating it anew, providing a consistent environment for the computation.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/how_to_opi.ipynb#_snippet_1

LANGUAGE: python
CODE:
```
# > Calculation is performed in `RUN`
working_dir = Path("RUN")
# > The `working_dir`is automatically (re-)created
shutil.rmtree(working_dir, ignore_errors=True)
working_dir.mkdir()
```

----------------------------------------

TITLE: Build OPI Project
DESCRIPTION: Builds the OPI project using Hatchling. The `--wheel` flag builds a wheel distribution, and `--sdist` builds a source distribution. Both can be specified or omitted to build default distributions.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_1

LANGUAGE: Shell
CODE:
```
uv build [--wheel]
uv build [--sdist]
```

----------------------------------------

TITLE: Codespell Spell Checking Output
DESCRIPTION: Example output from Codespell highlighting potential spelling errors in code files, suggesting corrections.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_10

LANGUAGE: text
CODE:
```
./examples/exmp003_opt/job.out:1004: contruction ==> construction
./examples/exmp003_opt/job.out:1480: contruction ==> construction
./examples/exmp003_opt/job.out:1954: contruction ==> construction
./examples/exmp003_opt/job.out:2437: contruction ==> construction
./src/opi/input/models/calculator.py:264: inout ==> input, in out
./build/lib/opi/input/models/calculator.py:264: inout ==> input, in out
6
```

----------------------------------------

TITLE: Mypy Static Type Checking Output
DESCRIPTION: Example output from Mypy indicating type errors found in the source code, including file paths, error messages, and suggestions for resolution.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/dev_guide.md#_snippet_8

LANGUAGE: text
CODE:
```
src/opi/output/core.py:1: error: Cannot find implementation or library stub for module named "calc_status"  [import-not-found]
    import calc_status
    ^
src/opi/output/core.py:1: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
src/opi/output/core.py:2: error: Cannot find implementation or library stub for module named "geometry"  [import-not-found]
[...]
src/opi/output/geometry.py:1: error: Cannot find implementation or library stub for module named "coord"  [import-not-found]
    import coord
    ^
Found 30 errors in 3 files (checked 15 source files)
```

----------------------------------------

TITLE: Python Workflow Example: ORCA Calculation Setup
DESCRIPTION: Demonstrates a typical workflow for setting up and running a quantum chemistry calculation using ORCA. It includes creating a working directory, defining molecular geometry in XYZ format, loading the structure, and executing an extrapolation function. This script serves as an example of how to integrate the energy calculation logic into a practical computational chemistry pipeline.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/extrapolate_cps_cbs.ipynb#_snippet_3

LANGUAGE: python
CODE:
```
if __name__ == "__main__":
    # > Create a working directory and XYZ file
    # > You can replace everything up to the next comment with your own directory or file
    working_dir = Path("RUN")
    working_dir.mkdir(exist_ok=True)

    xyz_data = """
3

O         -3.56626        1.77639        0.00000
H         -2.59626        1.77639        0.00000
H         -3.88959        1.36040       -0.81444
    """
    xyz_file = working_dir / "struc.xyz"
    with open(xyz_file, "w") as f:
        f.write(xyz_data)

    # > Load the molecular structure from XYZ file
    structure = Structure.from_xyz(xyz_file)

    # > Define a basename for the calculation files
    basename = "extrapolate_CPS_CBS"

    # > Perform ORCA calculations for DLPNO-CCSD(T1) CPS + CBS extrapolation and extrapolate
    df = extrapolation_cps_cbs(structure, basename, working_dir)

    # > Print the results
    print(df)
```

----------------------------------------

TITLE: Set Up Calculation Working Directory
DESCRIPTION: Configures a dedicated subdirectory for ORCA calculations, named 'RUN'. The script ensures this directory is clean by removing it if it exists and then creating it anew, providing a fresh environment for each calculation run.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/extopt.ipynb#_snippet_1

LANGUAGE: python
CODE:
```
# > Calculation is performed in `RUN`
working_dir = Path("RUN")
# > The `working_dir`is automatically (re-)created
shutil.rmtree(working_dir, ignore_errors=True)
working_dir.mkdir()
```

----------------------------------------

TITLE: Setup ORCA Calculation with Optimization
DESCRIPTION: Defines a Python function to set up an ORCA calculator. It configures the calculator with a basename, working directory, and assigns a molecular structure. It includes ORCA keywords for external optimization (EXTOPT) and general optimization (OPT), and specifies the path to an external tool wrapper script with arguments.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/extopt.ipynb#_snippet_3

LANGUAGE: python
CODE:
```
def setup_calc(basename : str, working_dir: Path, structure: Structure, ncores: int = 1) -> Calculator:
    # > Set up a Calculator object, the basename for the ORCA calculation is also set
    calc = Calculator(basename=basename, working_dir=working_dir)
    # > Assign structure to calculator
    calc.structure = structure

    # > List of simple keywords for ORCA
    sk_list = [
        ExternalTools.EXTOPT, # Set the extopt keyword for the ORCA input
        Opt.OPT # > Perform an optimization
    ]

    # > Use simple keywords in calculator
    calc.input.add_simple_keywords(*sk_list)

    # > Set the path to the wrapper script that should be used
    # > Without adjusting the path this notebook will not work!
    path_to_wrapper = "/home/full/path/to/orca-external-tools/mopac.sh"
    # Additional arguments for the wrapper script
    arguments = '"--method PM7"'
    
    # Add the block list to calculator
    calc.input.add_blocks(BlockMethod(ProgExt=path_to_wrapper,Ext_Params=arguments))

    # > Define number of CPUs for the calcualtion
    calc.input.ncores = ncores # > CPUs for this ORCA run (default: 1)

    return calc

basename = "pm7_opt"
calc = setup_calc(basename=basename, working_dir=working_dir, structure=structure)
```

----------------------------------------

TITLE: Install OPI via Pip
DESCRIPTION: Installs the ORCA Python Interface (OPI) package directly from PyPI using the pip package manager.

SOURCE: https://github.com/faccts/opi/blob/main/README.md#_snippet_0

LANGUAGE: shell
CODE:
```
pip install orca-pi
```

----------------------------------------

TITLE: Setup Working Directory and Unit Conversion
DESCRIPTION: Configures the execution environment by defining a working directory for ORCA calculations and setting a conversion factor for energy units. The directory is managed for clean execution.

SOURCE: https://github.com/faccts/opi/blob/main/docs/contents/notebooks/led.ipynb#_snippet_1

LANGUAGE: python
CODE:
```
# > Calculation is performed in `RUN`
working_dir = Path("RUN")
# > The `working_dir`is automatically (re-)created
shutil.rmtree(working_dir, ignore_errors=True)
working_dir.mkdir()
# > Conversion factor for atomic units to kcal/mol
unit_conversion = 627.509 
```

----------------------------------------

TITLE: Build Documentation
DESCRIPTION: Builds the project's documentation locally using the provided Makefile. This process requires the 'uv' package, which is typically installed by the Makefile itself.

SOURCE: https://github.com/faccts/opi/blob/main/README.md#_snippet_2

LANGUAGE: shell
CODE:
```
make html
```