LigninBuilder User's Guide.

This is the README/User Guide for LigninBuilder, a program to build 3D lignin structures from topological libraries.

Installation

The easiest way to install the VMD plugin aspect of LigninBuilder is to download this repository, and make VMD aware of its existence. Downloading the repository can be done via git clone or zip file downloads available at github. The downloaded repository is assumed to be in your home directory, which for the purposes of this example, we will call /home/user/LigninBuilder. Once downloaded, we append the plugin directory to the auto_path tcl variable within VMD, so that the plugin can be found. In the TkConsole, this is done via the following commands: tcl lappend auto_path /home/user/LigninBuilder/LigninBuilderPlugin package require ligninbuilder If package require ligninbuilder returns a version number, the plugin is loaded successfully, and can be used to generate lignin structures from lignin libraries. To install LigninBuilder so that it is recognized every time VMD starts, the lappend auto_path line should be added to your .vmdrc file, which contains configuration and settings information for VMD. For more information about .vmdrc files, please see the VMD userguide (scroll down towards the end of the page).

Usage

Once installed, the typical workflow is to build the lignin structures starting from an existing library, and subsequently minimizing the structures. An example using the included library for miscanthus is done as follows in VMD's TkConsole: tcl package require ligninbuilder ::ligninbuilder::buildfromlibrary "/home/user/LigninBuilder/libraries/Miscanthus Library.txt" Miscanthus ::ligninbuilder::minimizestructures Miscanthus namd2 "+p8" This will create a directory "Miscanthus" in your current working directory, and fill it with 100 lignin structure .psf and .pdb files (numbered L0-L99). The last line then minimizes these structures using NAMD with 8 processors, overwriting the .pdb file generated in the first step.

There are several things that can go wrong when minimizing structures. 1. Missing NAMD executable. In the example above, namd2 is in the execution path. The QwikMD tutorial demonstrates how to install NAMD such that it is put into the path. Note that here I am assuming that namd2 is a CPU-only version. As of this writing in July 2025, there is a bug in the gridforce implementation in namd3. Some structures will minimize fine with NAMD3, and some won't. My recommendation is to use NAMD 2.14-multicore downloaded directly from the UIUC website. While in namd3 ~~(which you could also use)~~ implements many of the features LigninBuilder needs on the GPU, that is not true in namd2, and you'll get an error message if you use a GPU build of namd2. 2. Missing force field term for your topology. The parameterized force field did not take into account new terms that might be required when adjacent linkages change atom types. For the included libraries, the required terms are all found in /home/user/LigninBuilder/extraterms-par_lignin.prm, which was generated by finding the missing terms within the full list of psf files created. If you create a new arrangement we have not encountered, please see the determinemissingterms.py section to replace the extraterms-par_lignin.prm file.

Creating Lignin Models from a SMILES String

If creating a full library proves difficult, we have developed a prototype implementation that uses SMILES representation of lignin as input, found in smilesdemo. The implementation uses some ancilliary python scripts to facilitate substructure recognition and to determine what parameters might be missing due to unforseen linkages. It requires the following python libraries to be available, most of which are installable via pip:

• Numpy
• ParmEd
• RDKit
• weighted_levenshtein

Some of the commands below are specific to Unix-style operating systems. If you'd like to follow along explicitly on a windows operating system, try the Windows Subsystem for Linux, but otherwise some of these commands will need to be translated.

We start in the smilesdemo directory by inspecting the demo.smiles file. Each line contains a SMILES string, which can be visualized in many different programs. There are three different lignin polymers specified. The first step is to create the instructions to create the lignin topology. This is done using the writepsfgen.py script: bash python writepsfgen.py This will create a psfgen.tcl file, which VMD can use to build the .psf files that represent the topology for each lignin polymer. This procedure uses RDKit to find substructures that match lignin fragments previously identified. Thus, there is no error checking whatsoever, and it is the user's responsibility to check the output for sanity at the end. In VMD's tkconsole, this script can be run via: tcl source psfgen.tcl This will create three .psf files, one for each lignin. Move these three files to a new folder output: bash mkdir output mv L*psf output Some of these polymers contain linkages and combinations that were not explicitly parameterized. We determine these parameters by analogy from the existing CGenFF and lignin force fields. bash python findmissingterms.py The script uses a weighted Levenshtein metric to penalize how "different" missing parameters are from existing parameters. The algorithm chooses values for these missing parameters by analogy from the closest set of existing parameters, and creates supplementary parameters in the file extraparameters.prm. Next, we assign coordinates to the psf files, again in the VMD TkConsole. tcl package require ligninbuilder ::ligninbuilder::makelignincoordinates output . The first argument is the input directory, and the second is the output directory relative to the input directory. The '.' signifies that the input and output directories should be the same. The extraparamters.prm file can be used as input to minimizestructures: tcl package require ligninbuilder ::ligninbuilder::minimizestructures output namd2 "+p8" "parameters extraparameters.prm \n parameters toppar/par_all36_cgenff.prm \n" The last argument is added into the NAMD configuration file right before minimization, and in this case serves to provide NAMD with the extra parameters it requires for the spirodienone. The minimized the structures will be in the output directory, and ready for further simulation.

SPRInG, a generator for polydisperse lignin polymers

One of the original shortcomings for LigninBuilder was that it was dependent on the lignin libraries generated by a program to which we do not have the source code. An effort lead by Vaidyanathan Sethuraman has overcome this obstacle by implementing a builder for polydisperse lignin, called SPRInG. The in-depth instructions for use are provided through the README posted to github, but an example for integration with LigninBuilder is provided in the SPRInGdemo directory, which is taken from the generic_builder directory within the SPRInG source tree. To build up an agglomeration of lignin polymers, one would call:

```bash

Generate the case inputs

python3 genconf.py inputsforpsfgen.inp cd casenum_1

Assemble psf/pdb pairs for individual polymers

vmd -dispdev text -e step1.tcl

Assemble individual polymers into a single system, create a GROMACS .top file, and identify missing terms.

vmd -dispdev text -e step2.tcl

Minimize psf/pdb pairs using NAMD.

vmd -dispdev text -e step3.tcl ```

Lignin-KMC

For arbitrary natural lignin, it is possible to use another python package, Lignin-KMC to generate lignin topologies suitable for 3D structure generation. The basic workflow for preparing structures like this would be to use Lignin-KMC to generate a psfgen script, which VMD can then interpret and feed into LigninBuilder. An example of this workflow is in the LigninKMCdemo directory, with the following two lines being sufficient (using the command line arguments for VMD).

bash python3 step1.py vmd -e step2.tcl

Minimization and further simulation would then proceed as in the previous examples, with an example VMD script that works for the example above contained as step3.tcl.

Citation

If you found this useful for your own scientific work, please read and cite:

Automated Transformation of Lignin Topologies into Atomic Structures with LigninBuilder Josh V. Vermaas, Lauren D. Dellon, Linda J. Broadbelt, Gregg T. Beckham, and Michael F. Crowley ACS Sustainable Chemistry & Engineering 2019 7 (3), 3443-3453 DOI: 10.1021/acssuschemeng.8b05665

For practical simulation, you would also likely cite the updated lignin force field:

Systematic parameterization of lignin for the CHARMM force field Josh V. Vermaas, Loukas Petridis, John Ralph, Michael F. Crowley, and Gregg T. Beckham Green Chemistry 2019 21, 109-122 DOI: 10.1039/C8GC03209B

If you want to make random natural lignins yourself, I highly recommend Lignin-KMC.

Lignin-KMC: A Toolkit for Simulating Lignin Biosynthesis Michael J. Orella, Terry Z. H. Gani, Josh V. Vermaas, Michael L. Stone, Eric M. Anderson, Gregg T. Beckham, Fikile R. Brushett, and Yuriy Román-Leshkov ACS Sustainable Chemistry & Engineering 2019 DOI: 10.1021/acssuschemeng.9b03534