COF-Landscaper

Automated structure generation, stacking-landscape screening, structure optimization, and PXRD-guided refinement for two-dimensional covalent organic frameworks.

COF-Landscaper is a Python package for building and analysing 2D covalent organic frameworks (COFs). It provides workflows for generating COF structures from molecular building blocks, exploring stacking configurations, optimizing candidate structures, simulating and comparing PXRD patterns with experimental data, and performing PXRD-guided in-plane lattice refinement.

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 project scope, I may be able to provide support, discuss collaboration, or offer a short one- to two-day online introduction for users with limited software or terminal experience. This can cover installation, setup, input preparation, and running the workflow on example or user-provided systems.

Installation

COF-Landscaper requires Python 3.12.

Standard Conda installation

The recommended setup is to use a dedicated Conda environment. If you do not already have Conda installed, a lightweight option is Miniforge.

Create and activate a new environment:

conda create -n coflandscaper python=3.12

conda activate coflandscaper

Upgrade pip:

python -m pip install --upgrade pip

Install COF-Landscaper from PyPI:

python -m pip install cof-landscaper

Check that the installation works:

python -c "import coflandscaper as cl; print(cl.__version__)"

Alternative virtual environment installation

If Python 3.12 is already available on your system, you can also use a standard virtual environment.

Check whether Python 3.12 is available:

python3.12 --version

If this command returns a Python 3.12 version, continue with the virtual environment setup (otherwise Python 3.12 can be installed from the official Python downloads page or through a platform-specific package manager).

Create a virtual environment.

python3.12 -m venv coflandscaper

Activate the virtual environment on macOS or Linux:

source coflandscaper/bin/activate

On Windows PowerShell, use:

.\coflandscaper\Scripts\Activate.ps1

Then install COF-Landscaper:

python -m pip install --upgrade pip

python -m pip install cof-landscaper

Example Files

A complete example workflow is included directly in the repository under:

example/

The example uses a single COF system and provides two complementary ways of running the COF-Landscaper workflow:

• cof-landscaper_local.ipynb: complete interactive workflow for running COF-Landscaper locally in a Jupyter notebook, including the individual workflow steps, visualization, analysis, and PXRD-guided refinement.

• cof-landscaper_hybrid.ipynb: companion notebook for the hybrid/HPC workflow. The main computational workflow is first executed using the Python script, typically on an HPC system, while the notebook is used afterwards to inspect the generated results, visualize the potential energy landscapes, compare simulated and experimental PXRD data, and perform PXRD-guided refinement.

The hybrid workflow is controlled by:

• cof-landscaper.py: executable Python workflow containing the main computational pipeline.
• cof-landscaper.params.json: configuration file containing the system and workflow parameters used by the Python script.

The Python workflow script is intended to remain unchanged; calculations are configured through cof-landscaper.params.json, where workflow parameters can be adjusted and optional settings added or removed as required. The example/ directory also contains the required example building-block files and experimental PXRD data. Both workflows use the same example system and input data.

Users can copy the example/ directory from the repository and modify the input structures, parameters, and workflow settings for their own systems.

Running the Notebooks

Install Jupyter support if you want to run the notebooks.

pip install jupyter ipykernel

Register the environment as a Jupyter kernel.

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

In VS Code or Jupyter, select the kernel:

Python (coflandscaper)

Run a test cell:

import coflandscaper as cl

Developer Setup

For development, install just and uv.

Clone the repository and enter the source directory.

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

cd COF-Landscaper

Set up the development environment.

just setup

Run code checks.

just check

Workflow Notes

• The workflow can be executed on a local machine using a CPU, although 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 cluster (GPU or CPU) 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:

Figure: COF-Landscaper workflow. Node and linker fragments are placed on a selected topological net to construct a single-layer COF structure. From this layer, COF-Landscaper generates a matrix of stacked COF structures that differ in their interlayer distance (ILD) and interlayer slipping (ILS) values. A machine-learned interatomic potential (MLIP) single-point energy calculation is performed for each stacking configuration, yielding a simplified potential-energy landscape. Low-energy minima on this landscape are used as starting guesses for structure optimization. The optimized COF structures can then be visualized, analysed, and used to simulate PXRD patterns for comparison with experimental PXRD data.

Required Input Files

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

In this context, the terms node and linker refer to the structural fragments used by the builder to assemble the framework. They do not correspond directly to the synthetic precursors. Instead, they describe the molecular fragments that are placed on the selected topological net during structure generation.

Figure: Schematic representation of fragment definition for COF-1. The full COF layer is shown on the left, with an enlarged local region indicating the conceptual bond cut used to define the input fragments. The resulting 3-connected node fragment and 2-connected linker fragment are shown on the right.

Supported topologies:

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.

Documentation

The full documentation is available on Read the Docs:

COF-Landscaper documentation

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