Usage¶

Installation of the htpolynet package gives access to the htpolynet command. Invoking htpolynet --help shows basic usage of the command. Normal usage requires issuing a subcommand.

$ htpolynet <subcommand> <subcommand-arguments>

The following subcommands are available:

Subcommand	Description
`run`	Perform a polymerization or “build a project” (use `--param-only` to stop after parameterization)
`info`	Report information about the `htpolynet` installation
`fetch-example`	Fetch one of the bundled example YAML configs
`input-check`	Report the atom count for the system the config would build, without running it
`postsim`	Perform one or more post-build MD simulations
`plots`	Generate plots from output of builds or post-build simulations
`analyze`	Perform `gmx`-style analyses of trajectories generated by post-build MD simulations
`gen-slurm-script`	Emit a SLURM batch script that runs `htpolynet run` for a given config
`make-viz`	Regenerate VMD visualization files (`.viz.psf` + `.viz.tcl`) from an existing `top` + `gro` pair

htpolynet <subcommand> -h provides subcommand-level help.

Typical Usage¶

htpolynet is designed to allow one to easily simulate many system replicas of a given polymerization recipe. A typical use of htpolynet to measure thermomechanical properties of a polymerized system is shown below.

        flowchart TD
    start(["Start"]):::startC

    mainCfg@{ shape: doc, label: "Main configuration<br/>file" }
    postCfg@{ shape: doc, label: "Postbuild simulation<br/>configuration file(s)" }
    trajCfg@{ shape: doc, label: "Trajectory analyses<br/>configuration file(s)" }

    subgraph trials ["Per-trial pipeline (&times;N)"]
        direction LR
        run["<tt>run</tt>"]
        postsim["<tt>postsim</tt>"]
        plots["<tt>plots</tt>"]
        analyze["<tt>analyze</tt>"]
        run --> postsim --> plots --> analyze
    end

    out1@{ shape: doc, label: "<i>E</i>, <i>T</i><sub>g</sub>" }
    out2@{ shape: doc, label: "density,<br/>FFV" }

    finish(["End"]):::endC

    start --> mainCfg --> run
    postCfg --> postsim
    postCfg --> plots
    trajCfg --> analyze
    plots --> out1
    analyze --> out2
    out1 --> finish
    out2 --> finish

    classDef startC fill:#a8e6a8,stroke:#2a7a3f,color:#1e5128
    classDef endC fill:#fadbd8,stroke:#a93226,color:#7b241c

Fig. 1 Example of a typical workflow for using htpolynet to measure a system density, fractional free volume, Young’s modulus E and glass-transition temperature T_g.¶

One typically begins in a clean base directory, and generates any necessary input molecular structure files, either in mol2 or pdb format. One then creates the main configuration file for the polymerization. One can then launch as many instances of htpolynet run as one likes; each creates a unique system. Once all the systems are built, one can then use htpolynet postsim to run post-build MD simulations, and then use htpolynet plots to extract E and T_g. If one of the post-build simulations is a long equilibration, one can then use htpolynet analyze to extract observables from that simulation’s trajectory file; here, we indicate that one can extract density and fractional free volume.

The htpolynet Directory Structure¶

The htpolynet command is typically issued inside of a base directory. I organize my simulations so that each particular system composition and cure protocol I am considering goes in its own base, and multiple runs in that base are all just replica simulations for conducting sample averages. Each such simulation is referred to as a project and each has its own project directory generated by htpolynet run.

A base directory can just be an empty directory to start with. I usually initialize a base directory by giving it a molecule library:

.
└── lib
    └── molecules
        ├── inputs
        │   └── STY.mol2
        └── parameterized

STY.mol2 is a mol2 file describing styrene in this example. htpolynet will store its parameterization information for all molecules and oligomers in the parameterized subdirectory.

htpolynet run will generate one or more project directories in the base directory.

htpolynet Subcommand Summaries¶

`htpolynet run`¶

run is used to generate a polymerized system (“build a project”) given directives in the configuration file and any required input monomer structures.

$ htpolynet run --help
usage: htpolynet run [-h] [-lib LIB] [-proj PROJ] [-diag DIAG] [-restart] [--no-banner]
                     [--force-parameterization] [--force-checkin] [--param-only]
                     [--loglevel LOGLEVEL]
                     config

positional arguments:
  config                input configuration file in YAML format

options:
  -h, --help            show this help message and exit
  -lib LIB              local user library of molecular structures and parameterizations
  -proj PROJ            project directory; "next" generates the next available; otherwise creates
                        or resumes (with -restart) a named directory
  -diag DIAG            diagnostic log file
  -restart              restart in latest proj dir (EXPERIMENTAL: broken at the cure stage; see
                        usage docs)
  --no-banner           suppress the startup banner
  --force-parameterization
                        force GAFF parameterization of any input mol2 structures
  --force-checkin       force check-in of generated parameter files to the system library
  --param-only          stop after parameterizing molecules without building the full system
  --loglevel LOGLEVEL   log level for the diagnostic file (debug|info)

<config> refers to the name of the configuration input file.
-lib names a directory that is treated as a local library of molecular structures. By default, this is assumed to be ./lib/ (that is, the directory you are in when you issue htpolynet run is expected by default to have a lib/ directory; if not, the Library subpackage of the htpolynet package will be queried for any data). At the beginning of a new run, lib/ should have one subdirectory called molecules. Under molecules should be the two directories inputs and parameterized. htpolynet will look for input mol2 or pdb files in lib/molecules/inputs, and “check-in” the results of parameterized molecules (i.e., Gromacs format gro, itp, and top files) in lib/molecules/parameterized.
-proj names the project directory. If not specified, or provided with the value next (the default), htpolynet will create the next auto-named project directory. These are always named as proj-0, proj-1, proj-2, etc. If no project directory exists and an explicit one is not specified by -proj, htpolynet creates the first one, proj-0:
```
.
├── lib
│   └── molecules
│       ├── inputs
│       │   └── STY.mol2
│       └── parameterized
│
└── proj-0
    ├── molecules
    │   └── parameterized
    ├── plots
    └── systems
```

The subdirectories of a project directory upon its creation are as follows.

molecules/parameterized – all molecular parameterization results appear here (in addition to being checked in to the library)

systems – system initializations, equilibrations, CURE iterations, and postcure equilibrations all get their own subdirectories here.

plots – various plots generated on the fly.

These will be explained more fully in the tutorials.

-diag names the diagnostic output file, and --loglevel specifies the logging level it uses. The default level is debug (i.e., the most informative).
-restart resumes the latest project directory from a previously-written checkpoint.

Warning

Restart is experimental and currently broken at the cure stage. Stages that complete before any cure iteration (do_initialization, do_densification, do_precure) skip correctly on resume, but the cure machinery fails on the first topology update after a restart with an internal “temp_idx N already claimed in temp2inst; bug” assertion. The root cause is that the cure controller’s per-iteration in-memory chain state is not fully reconstructible from the on-disk cure_state.yaml + reloaded gro/top/grx files. Treat restart as a development-only feature pending a redesign of cure-state persistence. Re-running from scratch with the same config is the safe path.
--force-parameterization signals that htpolynet should perform all molecular parameterizations from scratch even if parameterizations exist in the library.
--force-checkin signals that any parameterizations htpolynet performs should have their results “checked-in” to the library, even if previous parameterizations are there already.
--param-only stops after parameterizing all monomers and oligomer templates without proceeding to build the full system. This is useful for debugging parameterization issues before committing to a full run.

Parameterization caching¶

Every time htpolynet successfully parameterizes a molecule it copies the resulting mol2 / top / tpx / itp / gro / grx files into a per-user cache at ~/.htpolynet/molecules/parameterized/. On subsequent runs — anywhere on the filesystem, not just within the same project directory — that cache is consulted via the same lookup chain as the user library: a constituent named BPA will be picked up from the cache before antechamber/tleap is invoked, even if you started in a brand new working directory.

This is a performance feature (re-parameterizing AmberTools-heavy monomers can take minutes per species), but it has one important consequence:

Warning

A stale cache entry will silently get reused. If you fix a bug in a constituent’s SMILES, atom-naming, or charge method, the next run will still pick up the old parameterization from ~/.htpolynet/molecules/parameterized/. The symptom is usually a downstream error that does not seem to match the config you’re looking at.

Knobs to manage the cache:

HTPOLYNET_CACHE=<path> — environment variable that overrides the default cache location.
rm -rf ~/.htpolynet/molecules/parameterized — nuke everything and start fresh. In the container, the equivalent is docker volume rm <project>_htpolynet-home.
htpolynet run --force-parameterization <config> — re-parameterize every molecule for this run, ignoring the cache for lookup but without overwriting existing cache entries.
htpolynet run --force-parameterization --force-checkin <config> — re-parameterize and overwrite the cache entries with the new results. This is the right combination after fixing a constituent’s SMILES.

The cache is keyed by molecule name only. Renaming a constituent in your YAML (HIE → HEMA, say) bypasses the stale entry naturally.

`htpolynet info`¶

htpolynet info reports a snapshot of the installation and its surroundings.

$ htpolynet info
This is some information on your installed version of htpolynet
System library is /home/cfa/Git/htpolynet/src/htpolynet/resources
HTPolyNet git commit: c1db4f4 (uncommitted changes present)
Ambertools:
  antechamber (ver. 24.8 (conda))
        tleap (ver. 24.8 (conda))
     parmchk2 (ver. 24.8 (conda))
Gromacs:
          gmx (2025.4-conda_forge)
  GPU support: CUDA
GPUs:
  1 detected (0)
Available molecules in system library:
   DFA
   DGE
   ... (etc.)
Cached parameterized molecules:
   BPA
   DFA
   ... (one entry per cached monomer or oligomer template)
Available examples using htpolynet fetch-example
   0-liquid-styrene
   1-polystyrene
   2-bisgma-styrene-thermoset
   3-pacm-dgeba-epoxy-thermoset
   4-dfda-fde-epoxy-thermoset

The output reports the resolved path to the Library resources directory; the installed git commit; the fully resolved command names and versions for the required AmberTools executables (antechamber, tleap, parmchk2); the Gromacs binary that would be invoked along with its GPU-support status; the list of monomer mol2 files shipped in the system library; the contents of the per-user parameterization cache (see below); and the example builds available via fetch-example. Lines for components that are not installed (or not detected on PATH) are reported as such.

`htpolynet plots`¶

If invoked inside of a base directory containing one or more project directories, plots instructs htpolynet to generate some plots.

$ htpolynet plots --help
usage: htpolynet plots [-h] [--diags DIAGS [DIAGS ...]] [--proj PROJ [PROJ ...]]
                       [--cfg CFG [CFG ...]] [--buildplot {t,g,n,c} [{t,g,n,c} ...]]
                       [--traces {t,d,p} [{t,d,p} ...]] [--n_points N_POINTS N_POINTS]
                       [--plotfile PLOTFILE] [--no-banner] [--loglevel LOGLEVEL]
                       {diag,build,post}

positional arguments:
  {diag,build,post}     source of data to plot

options:
  -h, --help            show this help message and exit
  --diags DIAGS [DIAGS ...]
                        names of diagnostic log files (1 or more)
  --proj PROJ [PROJ ...]
                        name of project director[y/ies]
  --cfg CFG [CFG ...]   name of input config files
  --buildplot {t,g,n,c} [{t,g,n,c} ...]
                        build plot type: t=traces, g=2-D graph, n=homo-N between crosslinks,
                        c=cluster-size distributions
  --traces {t,d,p} [{t,d,p} ...]
                        trace types: t=temperature, d=density, p=potential energy
  --n_points N_POINTS N_POINTS
                        number of [cold-side,hot-side] data points for Tg line fits
  --plotfile PLOTFILE   name of output plot file
  --no-banner           suppress the startup banner
  --loglevel LOGLEVEL   log level for the diagnostic file (debug|info)

The plots subcommand manages plot generation from data from any of three sources: diagnostics, build, or post-build MD simulations. (Post-build MD simulations are described below for the htpolynet postsim subcommand.) We demonstrate examples of all three types in the tutorials.

`htpolynet fetch-example`¶

This will fetch one or more examples from the example_depot of the system Library.

$ htpolynet fetch-example --help
usage: htpolynet fetch-example [-h] {0,1,2,3,4,5,all}

positional arguments:
  {0,1,2,3,4,5,all}  example to fetch: 0-liquid-styrene, 1-polystyrene,
                     2-bisgma-styrene-thermoset, 3-pacm-dgeba-epoxy-thermoset,
                     4-dfda-fde-epoxy-thermoset, 5-htpb-ipdi

options:
  -h, --help         show this help message and exit

Fetching unpacks the requested example directly into the current directory. For example, to fetch the DFA-FDE epoxy thermoset example:

$ htpolynet fetch-example 4
Fetched 4-dfda-fde-epoxy-thermoset.yaml  (run with: htpolynet run 4-dfda-fde-epoxy-thermoset.yaml)
$ ls
4-dfda-fde-epoxy-thermoset.yaml

Each example is now a single self-contained YAML config. Monomer inputs are generated from SMILES strings embedded in the constituents section (see Molecular Structure Inputs), so there is no separate lib/molecules/inputs/ setup step and no shell wrapper to run. Drive it directly with:

$ htpolynet run 4-dfda-fde-epoxy-thermoset.yaml

htpolynet fetch-example all just grabs every example yaml.

`htpolynet input-check`¶

The purpose of this subcommand is to report the size of the initial system that would be created by the provided configuration file and monomer input structures.

$ htpolynet input-check 3-pacm-dgeba-epoxy-thermoset.yaml
Molecule DGE: 53 atoms, 200 molecules
Molecule PAC: 41 atoms, 100 molecules
3-pacm-dgeba-epoxy-thermoset.yaml: 14700 atoms in initial system.

`htpolynet postsim`¶

The purpose of the postsim subcommand is to control the execution of several types of post-build MD simulations.

$ htpolynet postsim -h
usage: htpolynet postsim [-h] [-proj PROJ [PROJ ...]] [-lib LIB] [-ocfg OCFG] [-cfg CFG]
                         [--no-banner] [--loglevel LOGLEVEL]

options:
  -h, --help            show this help message and exit
  -proj PROJ [PROJ ...]
                        name of project directory
  -lib LIB              local user library of molecular structures and parameterizations
  -ocfg OCFG            original htpolynet config file used to generate project(s)
  -cfg CFG              config file specifying the operations to perform
  --no-banner           suppress the startup banner
  --loglevel LOGLEVEL   log level for the diagnostic file (debug|info)

The simulations are controlled by the YAML-format config file, which is _distinct_ from the cfg file used to generate the project(s). The types of post-build MD simulations available are annealing, equilibration, temperature-ladder, and uniaxial deformation. Demonstrations of how the ladder and deformation simulations are used to compute the glass-transition temperature and Young’s modulus are detailed in the tutorials.

`htpolynet analyze`¶

The analyze subcommand provides a shortcut interfaces to selected gmx-style trajectory analysis calculations.

$ htpolynet analyze -h
usage: htpolynet analyze [-h] [-proj PROJ [PROJ ...]] [-lib LIB] [-ocfg OCFG] [-cfg CFG]
                         [--no-banner] [--loglevel LOGLEVEL]

options:
  -h, --help            show this help message and exit
  -proj PROJ [PROJ ...]
                        name of project directory
  -lib LIB              local user library of molecular structures and parameterizations
  -ocfg OCFG            original htpolynet config file used to generate project(s)
  -cfg CFG              config file specifying the operations to perform
  --no-banner           suppress the startup banner
  --loglevel LOGLEVEL   log level for the diagnostic file (debug|info)

The arguments of analyze are similar to those of postsim, except the configuration file specifies the analysis to perform, and the -proj specifies which project directories to perform the analysis in. We demonstrate using htpolynet analyze in the tutorials.

`htpolynet gen-slurm-script`¶

The gen-slurm-script subcommand emits a SLURM batch script that wraps a single htpolynet run invocation for the given YAML config. It is intended for launching builds on HPC clusters that schedule jobs through SLURM.

$ htpolynet gen-slurm-script -h
usage: htpolynet gen-slurm-script [-h] [-lib LIB] [-proj PROJ] [-diag DIAG] [-restart]
                                  [--no-banner] [--force-parameterization] [--force-checkin]
                                  [--param-only] [--loglevel LOGLEVEL] [--native] [--sif SIF]
                                  [--apptainer-alias APPTAINER_ALIAS] [-o OUTPUT]
                                  [--job-name JOB_NAME] [--partition PARTITION]
                                  [--account ACCOUNT] [--nodes NODES] [--ntasks NTASKS]
                                  [--ntasks-per-node NTASKS_PER_NODE]
                                  [--cpus-per-task CPUS_PER_TASK] [--time TIME] [--mem MEM]
                                  [--gres GRES]
                                  config

positional arguments:
  config                htpolynet YAML config file

options:
  -h, --help            show this help message and exit
  --native              run htpolynet natively instead of via Apptainer container
  --sif SIF             path to the Apptainer/Singularity .sif image (required unless --native)
  --apptainer-alias APPTAINER_ALIAS
                        container runtime command (default: apptainer)
  -o, --output OUTPUT   output script filename (default: submit_<config>.sh)

(Standard ``htpolynet run`` flags such as ``-lib``, ``-proj``, ``--param-only``, etc., are
forwarded into the ``htpolynet run`` line inside the script; SLURM directives such as
``--partition``, ``--time``, ``--mem``, ``--gres`` are written as ``#SBATCH`` lines at the
top of the script.)

Two execution modes are supported:

Containerized (default). The script invokes htpolynet run through an Apptainer/Singularity container. You must pass --sif <path> (or set sif: in the YAML config’s slurm: section).
Native. Pass --native to call the htpolynet binary on the cluster node directly, bypassing the container.

SLURM directives can be provided either on the command line (e.g., --partition gpu --time 4:00:00 --gres gpu:1) or as a slurm: block in the YAML config; CLI flags override YAML values when both are present.

`htpolynet make-viz`¶

The make-viz subcommand regenerates VMD visualization files (.viz.psf, .viz.tcl, and .viz.macros.tcl) from an existing Gromacs top + gro pair (plus the matching .grx for the macros). The PSF carries the real bond topology so VMD does not have to guess bonds from interatomic distances; the TCL is a small helper script that trims bonds longer than a 3 Å cutoff from the display (so PBC-crossing bonds in a crosslinked network do not draw as long sticks) and reports a fragment summary by mass. These files are normally created automatically at the end of a build; use make-viz to rebuild them after editing the topology or coordinates by hand, or to produce viz files for an arbitrary top/gro pair that was not produced by an htpolynet build.

$ htpolynet make-viz -h
usage: htpolynet make-viz [-h] [-top TOP] [-gro GRO] [-grx GRX] [-prefix PREFIX]

options:
  -h, --help      show this help message and exit
  -top TOP        input gromacs topology file (default: final.top)
  -gro GRO        input gromacs coordinate file (default: final.gro)
  -grx GRX        input htpolynet .grx (default: auto-detect <gro-stem>.grx; needed for the
                  constituent-selection macros)
  -prefix PREFIX  output basename; the .viz.psf, .viz.tcl, and .viz.macros.tcl are written
                  next to the input gro (default: stem of -gro)

Open the generated visualization in VMD with vmd <prefix>.viz.psf <prefix>.viz.gro -e <prefix>.viz.tcl. (Substitute your actual gro filename if it differs from the viz prefix.)

Selecting whole constituents¶

By design, the residue names in a cured system reflect the building blocks of each constituent, not the final assembled molecules. This is essential to htpolynet’s parameterization and bonding bookkeeping, but it makes interactive visualization awkward: in example 2 the bis-GMA molecules show up as BPA + 2 HIE; in example 5 each linear HTPB chain (DHT) is a sequence of OB + many TB + TBO residues, and each branched chain (THT) likewise.

When a .grx is available alongside the .gro, make-viz (and the end-of-build save step) additionally write <prefix>.viz.macros.tcl, which defines two layers of VMD atomselect macros keyed on constituent identity rather than residue name:

<NAME> — all atoms across every instance of constituent <NAME> (e.g. GMA, DHT, THT).
<NAME>_<NNN> — all atoms of one specific instance, where <NNN> is the global molecule index zero-padded to a uniform width.

The main .viz.tcl sources this file when it exists, so the macros are available immediately after vmd ... -e final.viz.tcl. Typical uses:

# show only the bis-GMA molecules (75 of them in example 2)
mol modselect 0 top GMA

# isolate a single HTPB chain by global molecule index
mol modselect 0 top DHT_125

# composable with the rest of VMD's selection language
mol modselect 0 top "THT and not hydrogen"

The residue-level view is untouched — selections like resname TBO or resname IPD still work — the constituent macros are an additive layer.

Usage¶

Typical Usage¶

The htpolynet Directory Structure¶

htpolynet Subcommand Summaries¶

htpolynet run¶

Parameterization caching¶

htpolynet info¶

htpolynet plots¶

htpolynet fetch-example¶

htpolynet input-check¶

htpolynet postsim¶

htpolynet analyze¶

htpolynet gen-slurm-script¶

htpolynet make-viz¶