What you need to install before using PolyFlin

PolyFlin requires the Biochemical and Organic Simulation System (BOSS) software to generate topology files for input into various molecular dynamics software. Please visit the Jorgensen Research Group website to download the BOSS software. Jika kamu hanya ingin menggunakan PolyFlin untuk mendesain struktur polimer (tanpa menginginkan topology file), maka kamu bisa melangkahi step ini.

To make it flexible in handling input and output files, PolyFlin utilizes OpenBabel. Please download OpenBabel from this page, install it, and ensure it can be executed via the terminal using the following command:

obabel --version

---

Install PolyFlin using pip

Make sure you have Python installed on your computer. You can check if Python is installed by running the following command in your terminal or command prompt:

python –version

If pip (Python Package Installer) is not already installed, you'll need to install it first. Most modern Python installations come with pip included by default. You can check if pip is installed by running the following command:

pip --version

If no error message is displayed, and a pip version is shown, pip is already installed. If not, you can follow the pip installation instructions for your system on the official pip website.

Now, you can install the PolyFlin package with the following command:

pip install polyflin

This will download and install the latest version of PolyFlin package from the PyPI (Python Package Index).

---

Portable use

PolyFlin module runs in Python, so you need to download and install Python.

After Python installation finish, you can download PolyFlin 1.0. Please make sure that your python is executable by running the following command on command prompt or terminal:

python –version

It should show you the Python version unless the Python executable file is not recognized by the system.

---

Once everything is in order, you are now prepared to create your unique polymer. Feel free to download the necessary materials for training.

Block Copolymer
Alternating Copolymer
Random Copolymer
Grafted Copolymer
Cyclic Copolymer
Star Copolymer
Nets Copolymer

PolyFlin usage after pip installation

To execute PolyFlin directly from the command prompt, you can use the following command:

polyflin -c "config.json"

In addition, you can also create a Python file such as 'my_file.py' and import polyflin. Here is an example:

from polyflin import polyflin

#extracting the configuration data
monomers, chains, output, atoms_map = polyflin.getData('config.json')

#creating the polymer structure
polymer = polyflin.createChains(chains, monomers, atoms_map)

#exporting the polymer files
polyflin.exportFiles(output, polymer)

---

Direct use of PolyFlin.py

PolyFlin runs in Python, and you can execute it using the following command:

python polyflin.py -c "config.json"

Before you execute the code, make sure that you have prepared the monomer structure file and the configuration file (file.config). You can download the example files at the download menu.

---

The configuration file contains 3 main arrays in JSON format.

{
"monomers":[...],

"chains":[...],

"output":{...}
}

You can read the details on how to prepare those arrays on the next menu.

Monomers array contains monomers data. Each item define one monomer.

{
"monomers":[
{
monomer1
},
{
monomer2
}
]
}

Each monomer data contains the following variables:

"code" : The monomer code in a capitalized letter (A-Z). Write inside a quote mark (example "A")

"file" : The path of the monomer structure file. Example "desktop/file/pNIPAM.smi"

"connections" : This array contains connection data for the current monomer, indicating its interactions with other monomers of the same type or different types. Each connections item contains the following data:

---

Connections Data for Monomer

{
"monomers":[
{
"code": "O",
"file": "oxygen.smi",
"connections":[
{
"to":"S",
"to_atom":0,
"my_atom":1,
"bond_type":"SINGLE"
}
]
},
{
monomer2
}
]
}

"to" : The targeted monomer code in a capitalized letter (A-Z) that will be connected to current monomer

"to_atom" : Atom index on targeted monomer that will form a bond to the current monomer

"my_atom" : Atom index on the current monomer that will form a bond to the targeted monomer

"bond_type" : The bond type that will be formed between the targeted and the current monomer. Options: "SINGLE", "DOUBLE", and "AROMATIC"

---

The "connections" data is used to link one monomer to another. For instance, if the polymer chain sequence is "AAABBB". The looping process starts from the left. Therefore, the monomer with the code A needs one "connections" data entry to connect to another monomer A. After 3 iterations, it connects to monomer B ("AAABBB"), so it also requires one "connections" data entry for monomer B. On the other hand, monomer B will only connect to monomer B, so its "connections" data item will be solely for monomer B.

Note: the connection of chain does not depend on the monomer "connections" data. The connection between chains is defined in the chain data. The next menu explains this in details.

Chains Data

Chains data declares the code, sequence, and number of replicate for each chain. The structure will look like the following:

"chains":[
{
chain1
},
{
chain2
}
]

---

Each chain contains the following variables:

"code" (required): The name of the chain in a word, can be uppercased or lowercased. Example: "MAIN"

"sequence" (required): The sequence of monomer composing the polymer chain. It use the monomer code to build the sequence. Example: "AAAABBBB", means that the chain contains 4 monomer A and 4 monomer B in one block copolymer chain. You can also introduce a chain-end group in one or both end of the chain. Example: "EAAAABBBBE", where E is a structure code of the chain-end group in the "monomers" list.

"nums" (required): The number of this chain will be replicated. Example: 3, for three chain replication

"cyclic" (optional): To connect two monomers in the chain and to form a cyclic shape. The following parameters should be declared in the "cyclic" data array.

---

Cyclic Data

Example code:

"chains":[
{
"code":"MAIN",
"sequence":"BSSSMMM",
"nums":3,
"cyclic":{
"bond_type":"SINGLE",
"head_mol":0,
"head_atom":2,
"tail_mol":6,
"tail_atom":1
}
},
{
chain2
}
]

The following variables are required to declare if you want to form cyclic shape polymer

"bond_type" (required): The bond type that will connect the head monomer and tail monomer. Options: "SINGLE", "DOUBLE", and "AROMATIC"

"head_mol" and "tail_mol" (required): The monomer code that acts as the head monomer and tail monomer. In the example code above, the head monomer can be monomer B and the tail monomer can be monomer M, or vice versa. The value of this variable should be in integer representing the index position of the monomer.

"head_atom" and "tail_atom" (required): The atoms that will interact and form bonding to connect head monomer and tail monomer. The value of this variable should be in integer representing the index position of the atom.

---

Connections Data for Chains

To connect chains, like making branch, connecting two main chain with a branch, etc, the following variables should be declared.

"chains":[
{
"code":"MAIN",
"sequence":"BSSSMMM",
"nums":3,
"cyclic":{
"bond_type":"SINGLE",
"head_mol":0,
"head_atom":2,
"tail_mol":6,
"tail_atom":1
}
},
{
"code":"BRANCH",
"sequence":"SSSB",
"nums":3,
"connections":[
{
"bond_type":"SINGLE",
"to_chain":"MAIN",
"to_mol":"M",
"to_atom":6,
"my_mol":0,
"my_atom":0
},
{
"bond_type":"SINGLE",
"to_chain":"MAIN",
"to_mol":"M",
"to_atom":6,
"my_mol":3,
"my_atom":3
}
]
}
],

"bond_type" (required): The bond type that will connect the "BRANCH" chain and "MAIN" chain. Options: "SINGLE", "DOUBLE", and "AROMATIC".

"to_chain" (required): The target chain that this "BRANCH" will connect to. The value is the code of the target chain.

"to_mol" (required): The monomer of the target chain that this "BRANCH" will connect to. The value can be the monomer code or monomer index.

"to_atom" (required): The atom of the monomer of target chain that this "BRANCH" will connect to. The value can be the atom symbol ("O" for oxygen), the atom index, or the atom indices in array if there are more than one targeted atom.

"my_mol" (required): The monomer of this chain that will connect to the target chain. The value can be the monomer code or monomer index.

"my_atom" (required): The atom of the monomer of this chain that will connect to the target chain. The value can only be the atom index.

This data array controls the output path, formats, and the treatment you wants to generate 2D or 3D structure. You can implement the following parameters.

"output":{
"name":"polymer",
"forcefield":"MMFF",
"obabel_func":"-p 6.5 --partialcharge gasteiger",
"format":["TOP", "png", "sdf", "smi", "mol", "mol2", "gro"]
}

"name" (required): The path and file name without extension. You can set the path and file name as "folder A/filename" or only the filename

"forcefield" (optional): You can declare this parameter if you want to generate 3D structure via geometrical optimization. The options are "MMFF" and "UFF"

"obabel_func" (optional): Outputs are generated using OpenBabel so you can add more additional features here. For example, you set sdf as the output. In PolyFlin, we convert the polymer file (initially in PDB) to SDF file using OpenBabel command, so you can set "--gen2D" to this variable so that the SDF output file will be in 2D coordinate. Any additional features for file conversion provided by OpenBibel are supported.

"add_hydrogen" (optional): Adding explicit hydrogens. Options: "TRUE" and "FALSE"

"format" (required): By default, a PDB file will always be generated, so you do not have to declare a PDB type. However, this format variable must have atleast one output; for example png. The output will be PNG and PDB files. Options: All files supported by OpenBabel can be generated.

To simultaneously generate all coordinate and topology files for MD simulation, set TOP as the output format. If the TOP format are set, there is no need to declare other output formats and the obabel_func variable.

Google Colab

Follow the tutorial here.

Local server

1. Follow all the instruction above for installation and download one polymer example provided. In this tutorial, we use the grafted copolymer (Hyaluronic acid grafted poly(N-isopropylacrylamide)). Extract the files into a folder; you can name the folder 'Simulation' or anything else.

Within the folder, you will have a 'config.json' file and monomer structures including the chain end group, hyaluronic acid, pnipam, and oxygen.

2. If you are using a portable script of PolyFlin (polyflin.py), place the script in the same folder containing the polymer data ('Simulation'). If you have installed PolyFlin from PyPi, you can skip this step.

3. Modify the 'config.json' file as needed. In this tutorial, we will add 'TOP' output format to generate topology and force field data as shown below and then save the file.

"format":["TOP"]

4. Open a command prompt, ensuring that you do so in the same folder as your prepared files.

5. Run the following code in your command prompt if you are using the portable script:

python polyflin.py -c "config.json"

or for installed PolyFlin, execute this code:

polyflin -c "config.json"

6. Wait for a while; the building time depends on the complexity of your design. Once it's finished, you will find outputs such as image in PNG format, the 3D structure of the polymer in PDB and GRO formats, and topology files for all the simulation software included here.

Make sure that LigParGen has been installed in your environment. If you encounter any issues while installing LigParGen or its dependencies, you have the option to use the CML output file and submit it to the PolyParGen website in order to generate GROMACS and LAMMPS topology data.

7. Use the output files of PolyFlin as an input for your simulating software. GROMACS users can refer to the tutorial provided here by Virginia Tech Department of Biochemistry.

The paper is submitted to a journal.

Abd. Kakhar Umar, Patanachai K. Limpikirati, and Jittima Amie Luckanagul. 2023. From Linear to Nets: Multiconfiguration Polymer Structure Generation with PolyFlin. Journal of Chemical Information and Modeling. DOI: 10.1021/acs.jcim.3c01221