Metadata-Version: 2.4
Name: cof-landscaper
Version: 2026.6.3.0
Summary: Python toolkit for building and analyzing 2D COF stacking-energy landscapes.
Maintainer-email: Gregor Lauter <gregor.lauter@gmx.de>
Project-URL: github, https://github.com/GregorLauter/COF-Landscaper
Project-URL: documentation, https://github.com/GregorLauter/COF-Landscaper
Requires-Python: ==3.12.*
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase>=3.27.0
Requires-Dist: mace-torch>=0.3.15
Requires-Dist: numpy<2.0
Requires-Dist: jax<0.5
Requires-Dist: jaxlib<0.5
Requires-Dist: py3dmol>=2.5.4
Requires-Dist: pymatgen>=2024.4.12
Requires-Dist: pormake>=0.2.3
Requires-Dist: torch-dftd>=0.5.2
Provides-Extra: notebook
Requires-Dist: jupyter>=1.1.1; extra == "notebook"
Requires-Dist: ipykernel>=7.1.0; extra == "notebook"
Dynamic: license-file

# COF-Landscaper

COF-Landscaper is a Python package for building and analyzing 2D COFs.

Researchers interested in applying COF-Landscaper to their own systems are welcome to contact me at gjl342@student.bham.ac.uk. Depending on availability and the scope of the project, I may be able to provide support or explore a possible collaboration.

## Platform Support

- Tested on macOS and Linux.
- Microsoft Windows is currently not tested.

## Installation

COF-Landscaper requires Python 3.12.

First open a terminal and check whether Python 3.12 is available:

```bash
python3.12 --version

```

If this command returns a Python 3.12 version, continue with the virtual environment setup below.

If you see an error such as `command not found: python3.12`, install Python 3.12 first.

On macOS, Python 3.12 can be installed with Homebrew:

```bash
brew install python@3.12
```

After installation, check again:

```bash
python3.12 --version
```

Create a virtual environment.

```bash
python3.12 -m venv coflandscaper
```

Activate the virtual environment.

```bash
source coflandscaper/bin/activate
```

Upgrade pip.

```bash
pip install --upgrade pip
```

Install COF-Landscaper from PyPI.

```bash
pip install cof-landscaper
```

## Example Files

After installation, COF-Landscaper can be imported and used directly in your own Python scripts or notebooks.

If you want to start from the provided example workflows, run:

```bash
cof-landscaper-copy-examples
```

This copies the example files into the current directory under:

```text
examples/
```

The copied examples include an executable Python workflow under:

```text
examples/python/
```

This folder contains the workflow script and a separate `cof-landscaper.params.json` file where the workflow settings can be configured. It also includes a minimal notebook for plotting simulated PXRD data together with experimental PXRD data after the workflow has finished.

The copied examples also include three notebook versions under:

```text
examples/notebook/
```

The notebook versions are:

- `cof-landscaper_configurable.ipynb`: full notebook with Markdown explanations for all configurable options.
- `cof-landscaper_default.ipynb`: default workflow notebook with explanations for the default settings.
- `cof-landscaper_minimal.ipynb`: minimal code-only workflow for running the notebook without extended explanations.

You can then edit the copied Python script, JSON parameter file, notebook, and input `.xyz` files for your own system.

## Running the Notebooks

Install Jupyter support if you want to run the notebooks.

```bash
pip install jupyter ipykernel
```

Register the environment as a Jupyter kernel.

```bash
python -m ipykernel install --user --name coflandscaper --display-name "Python (coflandscaper)"
```

In VS Code or Jupyter, select the kernel:

```text
Python (coflandscaper)
```

Run a test cell:

```python
import coflandscaper as cl
```

## Developer Setup

Install `just`.

Install `uv`.

Clone the repository and enter the source directory.

```bash
git clone https://github.com/GregorLauter/COF-Landscaper.git
cd COF-Landscaper
```

Set up the development environment.

```bash
just setup
```

Run code checks.

```bash
just check
```

## Workflow Notes

- The DFT (Crystal23) workflow requires additional external HPC infrastructure.
- The MLIP workflow can be executed on a local machine, but GPU access can provide a substantial speedup.
- For large systems, long screening workflows, or cases where local hardware is limiting, running the workflow on an external GPU or CPU cluster is recommended.
- If you are interested in applying COF-Landscaper but do not have access to suitable computational resources, feel free to contact me.

Workflow diagram:

![COF-Landscaper workflow](docs/readme/workflow.png)

## Required Input Files

The workflow requires building-block fragments provided as `.xyz` files.

In COF-Landscaper, the terms **node** and **linker** refer to the structural fragments used by the builder to assemble the framework. They do not necessarily correspond one-to-one to synthetic precursors. In practice, the node and linker files should represent the molecular fragments that are connected during structure generation.

The schematic below illustrates this distinction for COF-1:

<p align="center">
  <img src="docs/readme/cof-1.png" alt="COF-1 structure" width="500">
</p>

Node and linker fragments used for COF-1 structure generation:

<p align="center">
  <img src="docs/readme/cof-1_node.png" alt="COF-1 node fragment" width="280">
  <img src="docs/readme/cof-1_linker.png" alt="COF-1 linker fragment" width="280">
</p>

Supported topologies:

| Topology | Keyword | Description | Node amount | Node connectivity | Linker amount | Linker connectivity |
|---|---|---|---:|---|---:|---|
| Honeycomb | `hcb` | standard honeycomb. | 1 | 3 | 1 | 2 |
| Square lattice | `sql` |  | 1 | 4 | 1 | 2 |
| Binary honeycomb | `hcb_ab` | two different nodes nodes with no linker inbetween them linker. | 2 | 3 each | 0 | — |
| Kagome | `kgm` |  | 1 | 4 | 1 | 2 |

### Connection Points

Connection points must be marked with helium atoms (`He`) in the input `.xyz` files.

During preprocessing, COF-Landscaper converts these `He` atoms into pormake-compatible connection points. The number and geometry of the `He` atoms must match the selected topology and the intended connectivity shown in the table above.

Input requirements:

- `hcb`, `sql`, and `kgm` require one node `.xyz` file and one linker `.xyz` file.
- `hcb_ab` requires two node `.xyz` files and no linker file.
- By default, node files are read from `0_node/`.
- By default, linker files are read from `0_linker/` when required by the topology.
- Explicit paths can be provided with `input_nodes=[...]` and `input_linkers=[...]`.

Input fragments should ideally be pre-optimized with a generic force field, such as UFF, to remove severe steric clashes and obtain reasonable approximate bond lengths.

The subsequent pre-optimization step handles the assembled framework. Therefore, the main requirement at this stage is that the individual fragments are chemically sensible and can be connected cleanly by the builder.

The `.xyz` files can be prepared using any suitable molecular editor or visualizer, for example Avogadro, Mercury, or DrawMol.

## Where To Find Explanations

The full documentation is available on Read the Docs:

[COF-Landscaper documentation](https://cof-landscaper.readthedocs.io/)

Additional stepwise explanations of the computational workflow are provided in the Markdown cells of the example notebooks.
