.. _config_ref charmmff user_custom:

``user_custom``
===============

Use this attribute to bring your own CHARMM-format topology, parameter, or stream files
(e.g. a CGenFF stream for a small-molecule ligand) into a pestifer build, so that
``psfgen`` and NAMD pick them up without any further wiring.

How it works
^^^^^^^^^^^^

* Put your file(s) in one or more directories on disk.
* List each directory under ``searchpath``.  Every CHARMM-format file (``.rtf``, ``.top``, ``.str``, ``.prm``) in those directories is registered with pestifer and indexed by the ``RESI`` / ``PRES`` records it contains.
* When ``psfgen`` builds the system, any residue name in your input PDB whose definition lives in one of these files is automatically resolved: the file is copied into the run directory, a ``topology <file>`` line is emitted, and the file is registered in the pipeline so NAMD's parameter file list includes it as well.
* ``searchpath`` entries may contain ``~/`` (the user's home directory) or shell environment-variable references such as ``$HOME/foo`` or ``${SCRATCH}/charmm``; both are expanded before pestifer probes the directory.

Per-user toppar cache
^^^^^^^^^^^^^^^^^^^^^

``~/.pestifer/toppar/`` is a well-known per-user cache directory for custom CHARMM
stream files.  When it exists, pestifer **automatically prepends it to**
``searchpath`` so any ``.str`` / ``.rtf`` / ``.prm`` files dropped there are picked
up without requiring a ``user_custom`` block in the YAML.  This is the recommended
destination for the ``.str`` files generated by :ref:`subs_make_ligand_mol2`
(after running them through the CGenFF binary or web tool): once a parameter file
for, e.g., ``AP5`` lives in ``~/.pestifer/toppar/``, every subsequent build that
references that residue resolves it transparently.

Any directory the user lists in ``searchpath`` is loaded *after* the cache, so a
project-local entry overrides anything in ``~/.pestifer/toppar/`` (last-loaded
wins). When this happens pestifer emits a warning naming both files.

Segtype classification
^^^^^^^^^^^^^^^^^^^^^^

Every ``RESI`` / ``PRES`` found in a user_custom file is also registered with pestifer's
segtype machinery so the molecule parser can place those residues into segments.
By default each new residue is classified as ``ligand``.  Use the ``segtypes`` knob
below to override (e.g. mark a residue as ``cofactor`` instead).  An explicit
``psfgen.segtypes`` entry for the same resname always wins.

Caveats
^^^^^^^

* ``searchpath`` entries are **directories**; the per-extension lists below (``rtf``, ``str``, ``prm``) take **basenames only** -- any directory separator in those entries is rejected.
* A single ``.str`` file that contains both ``read rtf … END`` and ``read para … END`` blocks is sufficient -- you do not need to list it under more than one of ``rtf`` / ``prm``.
* ``custom`` is for files that ship with pestifer itself; user-supplied files belong here under ``user_custom``.
* Atom names in your input PDB must match the atom names declared in the ``RESI`` block of the stream file.  If they don't (e.g. RCSB PDBs typically use a different naming convention than CGenFF-generated streams), psfgen will build the residue topology but leave each unmatched atom at ``(0, 0, 0)``.  Add :ref:`psfgen.aliases.atom <config_ref psfgen aliases atom>` entries to bridge the two naming schemes.


Example:
++++++++

.. code-block:: yaml

   charmmff:
     user_custom:
       searchpath:
       - /path/to/my/custom/search/path/
       rtf:
       - a_file.rtf
       str:
       - a_file.str
       prm:
       - a_file.prm

Container-like attributes:

.. toctree::
   :maxdepth: 1

   user_custom/searchpath
   user_custom/rtf
   user_custom/str
   user_custom/prm
   user_custom/segtypes


.. raw:: html

   <div class="autogen-footer">
     <p>This page was generated by ycleptic v2.0.6 on 2026-05-28.</p>
   </div>