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*. .. code-block:: console $ htpolynet 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 -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. .. mermaid:: :alt: typical htpolynet usage workflow :caption: 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*:sub:`g`. flowchart TD start(["Start"]):::startC mainCfg@{ shape: doc, label: "Main configuration
file" } postCfg@{ shape: doc, label: "Postbuild simulation
configuration file(s)" } trajCfg@{ shape: doc, label: "Trajectory analyses
configuration file(s)" } subgraph trials ["Per-trial pipeline (×N)"] direction LR run["run"] postsim["postsim"] plots["plots"] analyze["analyze"] run --> postsim --> plots --> analyze end out1@{ shape: doc, label: "E, Tg" } out2@{ shape: doc, label: "density,
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 One typically begins in a clean base directory, and generates any necessary input :ref:`molecular structure files `, either in ``mol2`` or ``pdb`` format. One then creates the main :ref:`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*:sub:`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: .. code-block:: console . └── 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. .. code-block:: console $ 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) * ```` refers to the name of the :ref:`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``: .. code-block:: console . ├── 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: 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=`` — 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 _htpolynet-home``. * ``htpolynet run --force-parameterization `` — re-parameterize every molecule for this run, ignoring the cache for lookup but **without overwriting** existing cache entries. * ``htpolynet run --force-parameterization --force-checkin `` — 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. .. code-block:: console $ 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 :ref:`below `); and the example builds available via :ref:`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. .. code-block:: console $ 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: ``htpolynet fetch-example`` !!!!!!!!!!!!!!!!!!!!!!!!!!! This will fetch one or more examples from the ``example_depot`` of the system ``Library``. .. code-block:: console $ 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: .. code-block:: console $ 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 :ref:`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. .. code-block:: console $ 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. .. code-block:: console $ 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. .. code-block:: console $ 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. .. code-block:: console $ 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_.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 `` (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. .. code-block:: console $ 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 .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 .viz.psf .viz.gro -e .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 ``.viz.macros.tcl``, which defines two layers of VMD ``atomselect`` macros keyed on **constituent** identity rather than residue name: * ```` — all atoms across every instance of constituent ```` (e.g. ``GMA``, ``DHT``, ``THT``). * ``_`` — all atoms of one specific instance, where ```` 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: .. code-block:: tcl # 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.