===================================
xtb_step Phase A -- File Drop Notes
===================================

This drop fixes the two cookiecutter-template issues identified in the
review and bootstraps the ``data/`` directory.  No real plug-in
functionality yet -- that is Phase B.

Everything here is meant to be copied into your local ``xtb_step``
working tree at the same relative paths.  After copying:

::

    make lint
    make install
    make test

should all still pass -- this drop does not break anything and does
not add functionality, only foundation.


File-by-file
============

Modified files (replace existing)
---------------------------------

``xtb_step/xtb.py``
    Two changes only:

    1. ``pkg_resources`` import and ``Path(pkg_resources.resource_filename(...))``
       replaced with ``importlib.resources.files("xtb_step") / "data"``.
       ``from pathlib import Path`` was used only for that one wrapping
       and has been removed.
    2. The ``run()`` method body has been replaced.  The cookiecutter
       generated the LAMMPS/MOPAC-style "build a single ``molssi.dat``
       from ``node.get_input()`` and run the binary once" template,
       which is wrong for xtb -- xtb does one task per invocation.
       The new ``run()`` follows the FHI-aims pattern: iterate the
       subflowchart and let each substep call its own ``run()``.

    Everything else (``description_text``, ``analyze``, ``set_id``,
    docstrings, namespace, group) is unchanged from the cookiecutter.

``xtb_step/energy.py``, ``xtb_step/optimization.py``, ``xtb_step/frequencies.py``
    One change only in each: ``pkg_resources`` -> ``importlib.resources``
    in the property-loader at the top of the file.  Class bodies,
    placeholder ``time`` parameter, and the cookiecutter-generated
    ``run()`` and ``analyze()`` are all left alone.  These three files
    will get their real content in Phase B.


New files
---------

``xtb_step/substep.py``
    Base class for all substeps (Energy, Optimization, Frequencies, and
    any future MD/metadynamics/etc. substep).  Holds the genuinely
    common machinery:

    * ``check_periodicity(configuration)`` -- prints a clear message
      via the step printer and raises ``RuntimeError`` for periodic
      input.
    * ``write_coord_xyz(directory, configuration)`` -- writes the
      ``coord.xyz`` file consumed by xtb.
    * ``run_xtb(args, return_files, env)`` -- invokes xtb via the SEAMM
      executor, reading the per-plug-in ``xtb.ini`` from the SEAMM root
      directory and falling back to the bundled ``data/xtb.ini``
      template if the user's does not yet exist.
    * ``read_xtbout_json(directory, filename)`` -- best-effort parse of
      the JSON output produced by ``--json``.

    Phase B will switch ``Energy``, ``Optimization``, and ``Frequencies``
    over to inherit from ``Substep``.  The class is not imported in
    ``__init__.py`` since users do not instantiate it directly.

``xtb_step/data/seamm-xtb.yml``
    Conda environment file for the auto-installer.  Pulls Python and
    xtb from conda-forge.  *Verify before using:* the conda-forge xtb
    package name -- check with ``conda search -c conda-forge xtb``.

``xtb_step/data/xtb.ini``
    Default ini configuration template, modeled on ``dftbplus.ini``
    since DFTB+ is also conda-default from conda-forge.  Sections:
    ``[docker]`` and ``[local]``, with ``installation = conda`` and
    ``conda-environment = seamm-xtb`` as the defaults.  The seamm
    installer would normally copy this file (or write a customized
    version) into the user's SEAMM root directory.

``xtb_step/data/properties.csv``
    Replaces the empty stub.  Thirteen v1 seed properties using the
    ``<name>#xTB#{model}`` naming convention from ``mopac_step``.
    ``{model}`` is filled in with the active method (e.g. ``GFN2-xTB``)
    at runtime.

``xtb_step/data/references.bib``
    Extends the cookiecutter stub.  The auto-generated self-cite has
    its title fixed to ``xTB plug-in for SEAMM`` (was ``Xtb``) and a
    realistic organization/address.  Six new BibTex entries for the
    xTB method family:

    * ``Bannwarth2021`` -- general xTB review (cite at level 1 always)
    * ``Bannwarth2019`` -- GFN2-xTB
    * ``Grimme2017``    -- GFN1-xTB
    * ``Pracht2019``    -- GFN0-xTB (ChemRxiv preprint -- no journal paper as of v1)
    * ``Spicher2020``   -- GFN-FF
    * ``Ehlert2021``    -- ALPB / GBSA solvation


Not changed
===========

``setup.py``, ``setup.cfg``, ``__init__.py``, the three ``*_step.py``
helper classes for stevedore, the three ``tk_*.py`` GUI classes,
``metadata.py``, and the three ``*_parameters.py`` files are unchanged.
The entry points in ``setup.py`` are already correctly wired for all
four classes.

``metadata.py`` will be filled in during Phase B (it currently has
example commented-out blocks but no live ``metadata["results"]``
dictionary).


What to expect after copying
============================

After ``make install`` the package will import cleanly with no
``DeprecationWarning`` from ``pkg_resources``, the ``data/`` directory
will be on disk for ``importlib.resources`` to find, and the top-level
``xTB`` step's ``run()`` will iterate substeps correctly.  But the
substeps themselves still do nothing useful -- each one prints its
parameters and calls a placeholder ``analyze()``.  That is what
Phase B fixes.