cof-landscaper 2026.6.17.0

Python toolkit for building and analyzing 2D COF stacking-energy landscapes.

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 [e-mail]. 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:

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:

brew install python@3.12

After installation, check again:

python3.12 --version

Create a virtual environment.

python3.12 -m venv coflandscaper

Activate the virtual environment.

source coflandscaper/bin/activate

Upgrade pip.

pip install --upgrade pip

Install COF-Landscaper from PyPI.

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:

cof-landscaper-copy-examples

This copies the example files into the current directory under:

examples/

The copied examples include an executable Python workflow under:

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:

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.

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

Install just.

Install 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 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:

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:

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

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

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