From 4f6f8d67245f9174a39553e2b2409e1b6ec1f393 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 11:59:25 +0200 Subject: [PATCH 01/12] docs: modernize documentation structure --- .github/workflows/docs.yml | 83 ++++---- docs/source/_static/css/custom.css | 38 ++-- docs/source/_templates/package.rst | 5 +- docs/source/analyses/index.rst | 82 ++++++++ docs/source/analyses/momentum.rst | 42 ++++ docs/source/analyses/msd.rst | 61 ++++++ docs/source/analyses/rdf.rst | 61 ++++++ docs/source/analyses/vacf.rst | 64 ++++++ docs/source/analyses/vibrations.rst | 55 +++++ docs/source/conf.py | 192 +++++++++--------- docs/source/data/index.rst | 88 ++++++++ docs/source/developerGuide/developerGuide.rst | 150 +++++++------- docs/source/getting-started.rst | 99 +++++++++ docs/source/index.rst | 111 ++++++++-- docs/source/reference/api.rst | 67 ++++++ docs/source/reference/cli.rst | 96 +++++++++ docs/source/reference/index.rst | 34 ++++ docs/source/userGuide/analysisOutputFiles.rst | 5 +- docs/source/userGuide/inputFile.rst | 139 ++++++++++--- docs/source/userGuide/userGuide.rst | 169 ++------------- pyproject.toml | 8 +- 21 files changed, 1206 insertions(+), 443 deletions(-) create mode 100644 docs/source/analyses/index.rst create mode 100644 docs/source/analyses/momentum.rst create mode 100644 docs/source/analyses/msd.rst create mode 100644 docs/source/analyses/rdf.rst create mode 100644 docs/source/analyses/vacf.rst create mode 100644 docs/source/analyses/vibrations.rst create mode 100644 docs/source/data/index.rst create mode 100644 docs/source/getting-started.rst create mode 100644 docs/source/reference/api.rst create mode 100644 docs/source/reference/cli.rst create mode 100644 docs/source/reference/index.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8480df72..add34a8d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,62 +1,49 @@ -# Sample workflow for building and deploying a Jekyll site to GitHub Pages name: Docs on: - # Runs on pushes targeting the default branch push: - branches: - - '*' - - # Allows you to run this workflow manually from the Actions tab + branches: [main, dev] + pull_request: + branches: [main, dev] workflow_dispatch: -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: - contents: write - pages: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false + contents: read jobs: - # Build job - build: + build-docs: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Python - uses: actions/setup-python@v5 + - uses: actions/checkout@v7 with: - python-version: 3.12 + fetch-depth: 0 + - uses: actions/setup-python@v7 + with: + python-version: "3.12" cache: pip - - - name: Requirements - run: | - sudo apt-get update - sudo apt-get install -y python3-sphinx - python -m pip install --upgrade pip - python -m pip install -e ".[docs]" - - - name: Build - run: | - cd docs - make clean - rm -f source/code/* - bash autodoc.sh - make html - cd build/html - touch .nojekyll - shell: bash - - # Deployment job - - name: deploy - uses: JamesIves/github-pages-deploy-action@releases/v4 + - name: Install the package and documentation dependencies + run: python -m pip install -e ".[docs]" + - name: Build the documentation + run: python -m sphinx -W --keep-going -b html docs/source docs/build/html + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v5 with: - branch: gh-pages # The branch the action should deploy to. - folder: docs/build/html # The folder the action should deploy. - if: github.ref_name == 'main' # Only deploy on pushes to the main branch + path: docs/build/html + + deploy-docs: + needs: build-docs + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + concurrency: + group: pages + cancel-in-progress: false + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index d4bed75f..a7e33447 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -1,34 +1,36 @@ -@import url("theme.css"); - -.wy-nav-content { - max-width: 80%; +.sidebar-logo { + width: 4rem; } -dl.py.class { - dt.sig.sig-object.py { - display: block !important; - } +.sidebar-brand-text { + font-weight: 700; + letter-spacing: 0; } -.py.property { - display: block !important; +.sd-card { + border-radius: 4px; + box-shadow: none; } -.sig.sig-object.py dl { - margin-block-end: 0.0em; +code.literal { + border-radius: 2px; +} - & dd { - margin-bottom: 0.0em; - } +.table-wrapper { + overflow-x: auto; } -.wy-table-responsive table.analysis-output-columns { +table.analysis-output-columns { min-width: 640px; width: 100%; } -.wy-table-responsive table.analysis-output-columns th, -.wy-table-responsive table.analysis-output-columns td { +table.analysis-output-columns th, +table.analysis-output-columns td { vertical-align: top; white-space: normal; } + +.pq-command-table td:first-child { + white-space: nowrap; +} diff --git a/docs/source/_templates/package.rst b/docs/source/_templates/package.rst index fadf61ee..195448b0 100644 --- a/docs/source/_templates/package.rst +++ b/docs/source/_templates/package.rst @@ -1,4 +1,5 @@ -{# The :autogenerated: tag is picked up by breadcrumbs.html to suppress "Edit on Github" link #} +{# Generated packages stay outside the curated user-facing navigation. #} +:orphan: :autogenerated: {{ name }} @@ -116,4 +117,4 @@ Reference --------- -{%- endif %} \ No newline at end of file +{%- endif %} diff --git a/docs/source/analyses/index.rst b/docs/source/analyses/index.rst new file mode 100644 index 00000000..b5e891c4 --- /dev/null +++ b/docs/source/analyses/index.rst @@ -0,0 +1,82 @@ +Analyses +======== + +PQAnalysis covers structural organization, translational dynamics, +time-correlation spectra, molecular normal modes and conservation diagnostics. +Choose the observable from the physical question and from the data recorded by +the simulation. + +.. grid:: 1 2 3 3 + :gutter: 2 + + .. grid-item-card:: Radial distribution + :link: rdf + :link-type: doc + + Pair structure, preferred separations and coordination numbers. + + .. grid-item-card:: Mean square displacement + :link: msd + :link-type: doc + + Translational motion and Einstein-relation diffusion estimates. + + .. grid-item-card:: VACF and spectra + :link: vacf + :link-type: doc + + Velocity or charge-flux correlation and frequency-domain spectra. + + .. grid-item-card:: Vibrational analysis + :link: vibrations + :link-type: doc + + Hessian normal modes, wavenumbers, force constants and IR intensities. + + .. grid-item-card:: Total momentum + :link: momentum + :link-type: doc + + Frame-resolved linear momentum and center-of-mass drift diagnostics. + + .. grid-item-card:: Output schemas + :link: ../userGuide/analysisOutputFiles + :link-type: doc + + Exact columns, units, normalizations and format conversion behavior. + +Choose by input data +-------------------- + +.. list-table:: Analysis inputs and primary observables + :header-rows: 1 + :widths: 24 32 44 + + * - Analysis + - Required physical data + - Primary observable + * - RDF + - Positions and periodic cell + - :math:`g_{AB}(r)` and cumulative coordination + * - MSD + - Positions and periodic cell + - :math:`\langle |\mathbf{r}(t)-\mathbf{r}(0)|^2\rangle` + * - VACF + - Velocities and frame time step + - Normalized :math:`C_v(t)` and its spectrum + * - Vibrations + - Structure, masses and Cartesian Hessian + - Normal-mode wavenumbers and force constants + * - Momentum + - Velocities and atomic masses + - :math:`|\sum_i m_i\mathbf{v}_i|` per frame + +.. toctree:: + :hidden: + :maxdepth: 1 + + rdf + msd + vacf + vibrations + momentum diff --git a/docs/source/analyses/momentum.rst b/docs/source/analyses/momentum.rst new file mode 100644 index 00000000..18675d67 --- /dev/null +++ b/docs/source/analyses/momentum.rst @@ -0,0 +1,42 @@ +Total Linear Momentum +===================== + +For every velocity frame, PQAnalysis evaluates the selected atoms' total +linear momentum, + +.. math:: + + \mathbf{P}(t) = \sum_i m_i\mathbf{v}_i(t), + +and writes its scaled norm. This is a diagnostic for center-of-mass drift and +momentum conservation, not a substitute for inspecting the thermostat, +constraints or integration scheme. + +Run the diagnostic +------------------ + +.. code-block:: console + + $ pqanalysis check_momentum velocity.vel \ + --selection all \ + --output momentum.dat + +The default scale of ``1e-15`` converts PQ velocity-trajectory values from +amu Angstrom s\ :sup:`-1` to amu Angstrom fs\ :sup:`-1`. Use ``--scale`` when +the input convention differs. + +Interpretation +-------------- + +The output contains a one-based frame index and the scaled momentum norm. A +systematic increase can indicate center-of-mass drift. Oscillatory or noisy +behavior must be interpreted relative to the total mass, velocity scale and +numerical precision. + +PQ velocity trajectories are parsed in single precision. Norms below roughly +``1e-7 * sum_i(m_i * |v_i|) * scale`` are therefore parsing noise rather than +resolved physical drift. + +See :ref:`analysis-output-momentum` for the output schema. Python workflows +can call :func:`PQAnalysis.analysis.momentum.api.check_momentum` or use +:class:`PQAnalysis.analysis.momentum.momentum.Momentum` directly. diff --git a/docs/source/analyses/msd.rst b/docs/source/analyses/msd.rst new file mode 100644 index 00000000..8698a806 --- /dev/null +++ b/docs/source/analyses/msd.rst @@ -0,0 +1,61 @@ +Mean Square Displacement +======================== + +The mean square displacement measures translational motion over a lag time. +For Cartesian component :math:`\alpha`, PQAnalysis evaluates multiple time +origins according to + +.. math:: + + \mathrm{MSD}_{\alpha}(\tau) = + \left\langle [r_{i\alpha}(t+\tau)-r_{i\alpha}(t)]^2 \right\rangle_{i,t}. + +Coordinates are unwrapped with the periodic cell before displacements are +accumulated. + +Minimal input +------------- + +.. code-block:: text + + traj_files = trajectory.xyz + target_selection = O + out_file = msd.dat + window = 1000 + gap = 10 + time_step = 0.001 + fit_window = 200 + +.. code-block:: console + + $ pqanalysis msd msd.in + +``window`` is the largest lag in frames and must be divisible by ``gap``. +``gap`` controls the spacing between time origins. ``time_step`` is expressed +in ps and enables diffusion fitting; ``fit_window`` selects the trailing +points used by that fit. + +Interpretation +-------------- + +The output contains the lag index and the x, y and z components in +Angstrom squared. Their sum is the total three-dimensional MSD. In an +isotropic diffusive regime, + +.. math:: + + D = \frac{1}{6}\frac{d}{dt}\mathrm{MSD}_{\mathrm{total}}(t). + +PQAnalysis also fits each Cartesian component with the corresponding +one-dimensional factor. The resulting coefficients, uncertainties and +:math:`R^2` values are written to the log file in m\ :sup:`2`/s. A fit is +physically meaningful only over a linear diffusive interval; short-time +ballistic motion and poorly sampled long lags should not be included blindly. + +Output and API +-------------- + +See :ref:`analysis-output-msd` for the exact table layout. The input-file entry +point is :func:`PQAnalysis.analysis.msd.api.msd`; direct workflows can use +:class:`PQAnalysis.analysis.msd.msd.MSD` and inspect its total MSD and fit +results. diff --git a/docs/source/analyses/rdf.rst b/docs/source/analyses/rdf.rst new file mode 100644 index 00000000..63809510 --- /dev/null +++ b/docs/source/analyses/rdf.rst @@ -0,0 +1,61 @@ +Radial Distribution Function +============================ + +The radial distribution function measures the probability of finding a target +atom at distance :math:`r` from a reference atom relative to an ideal gas at +the same effective target density. For histogram bin :math:`i`, PQAnalysis +uses + +.. math:: + + g_i = \frac{H_i}{\rho_T N_R N_F \Delta V_i}, + +where :math:`H_i` is the eligible pair count, :math:`\rho_T` the target number +density, :math:`N_R` the number of reference atoms, :math:`N_F` the number of +frames and :math:`\Delta V_i` the spherical-shell volume. + +Minimal input +------------- + +.. code-block:: text + + traj_files = trajectory.xyz + reference_selection = O + target_selection = H + delta_r = 0.05 + r_max = 8.0 + out_file = rdf.dat + +.. code-block:: console + + $ pqanalysis rdf rdf.in + +``restart_file`` and ``moldescriptor_file`` are unnecessary for a basic +species RDF. They are required when ``no_intra_molecular = True`` is used to +exclude pairs belonging to the same molecule. PQAnalysis can infer the usual +PQ companion filenames when they are beside the trajectory. + +Interpretation +-------------- + +* Peaks mark preferred pair separations; minima separate coordination shells. +* :math:`g(r) \approx 1` indicates bulk-like, uncorrelated pair density at that + distance. +* The cumulative coordination column gives the mean number of eligible target + atoms per reference atom inside the current upper bin edge. +* Self pairs are excluded. Intramolecular pairs are included unless molecular + topology is supplied and explicitly excluded. + +Normalization, finite-size effects, selection definitions and trajectory +sampling should be considered before comparing RDFs from different systems. + +Output and API +-------------- + +See :ref:`analysis-output-rdf` for the five output columns and their exact +normalization. The main Python entry point is +:func:`PQAnalysis.analysis.rdf.api.rdf`; lower-level calculations use +:class:`PQAnalysis.analysis.rdf.rdf.RDF`. + +The complete input-key table is documented with +:class:`PQAnalysis.analysis.rdf.rdf_input_file_reader.RDFInputFileReader`. diff --git a/docs/source/analyses/vacf.rst b/docs/source/analyses/vacf.rst new file mode 100644 index 00000000..b4284dd2 --- /dev/null +++ b/docs/source/analyses/vacf.rst @@ -0,0 +1,64 @@ +VACF and Spectra +================ + +The normalized velocity autocorrelation function describes how rapidly atomic +velocities lose memory of their initial direction: + +.. math:: + + C_v(t) = + \frac{\left\langle \sum_i \mathbf{v}_i(0)\cdot\mathbf{v}_i(t)\right\rangle} + {\left\langle \sum_i \mathbf{v}_i(0)\cdot\mathbf{v}_i(0)\right\rangle}. + +PQAnalysis can transform the correlation to a wavenumber-domain spectrum. If +static or time-dependent partial charges are supplied, it correlates +:math:`q_i\mathbf{v}_i` instead, producing a charge-flux spectrum that +approximates an infrared spectrum. + +Minimal input +------------- + +.. code-block:: text + + traj_files = trajectory.vel + target_selection = all + out_file = vacf.dat + time_step = 0.001 + window = 2500 + gap = 5 + spectrum_file = spectrum.dat + ftsize = 5000 + window_function = exponential + window_param = 4.0 + +.. code-block:: console + + $ pqanalysis vacf vacf.in + +The time step is specified in ps. ``window_function`` accepts +``exponential``, ``hann`` and ``blackman``. The default sliding-origin method +matches the legacy calculation; ``method = fft`` selects a denser-origin +Wiener-Khinchin estimator. + +Interpretation +-------------- + +* A rapidly decaying VACF indicates fast velocity decorrelation. +* Negative regions indicate backscattering or cage motion. +* The frequency spectrum depends on the sampling interval, correlation length, + apodization window and zero-padding size. +* Charge-flux spectra require physically meaningful partial charges and should + not be interpreted as absolute IR intensities without further calibration. + +Output and API +-------------- + +See :ref:`analysis-output-vacf` for correlation and spectrum columns. The +input-file entry point is :func:`PQAnalysis.analysis.vacf.api.vacf`. Direct +calculations use :class:`PQAnalysis.analysis.vacf.vacf.VACF`, while +:func:`PQAnalysis.analysis.vacf.spectrum.vacf_spectrum` performs the spectral +transform. + +Discrete line spectra can be broadened independently with +``pqanalysis build_spectrum``; see :ref:`analysis-output-spectrum` for its +output convention. diff --git a/docs/source/analyses/vibrations.rst b/docs/source/analyses/vibrations.rst new file mode 100644 index 00000000..fb05df81 --- /dev/null +++ b/docs/source/analyses/vibrations.rst @@ -0,0 +1,55 @@ +Vibrational Analysis +==================== + +Vibrational analysis diagonalizes the mass-weighted Cartesian Hessian. Its +eigenvectors define normal modes and its eigenvalues determine signed +wavenumbers. Negative wavenumbers represent imaginary modes associated with +negative curvature of the potential-energy surface. + +Minimal input +------------- + +.. code-block:: text + + structure_file = structure.rst + hessian_file = hessian.dat + out_file = wavenumbers.dat + normal_modes_file = normal_modes.dat + modes_file = modes.xyz + modes = positive + unit = kcal + hessian_sign = auto + +.. code-block:: console + + $ pqanalysis vibrations vibrations.in + +``structure_file`` may be a PQ restart or a single-frame XYZ file. ``unit`` +describes the Hessian energy unit and accepts ``kcal``, ``hartree`` or ``ev``. +``hessian_sign = auto`` evaluates both supported sign conventions and chooses +the one with more non-negative vibrational modes. + +Scientific checks +----------------- + +* A stable, fully optimized minimum should not contain genuine imaginary + internal modes. Small values can arise from incomplete optimization or + numerical noise. +* Translational and rotational near-zero modes depend on boundary conditions, + molecular geometry and numerical precision. +* IR intensities require a ``moldescriptor_file`` containing partial charges. +* The Hessian coordinate order, structure atom order and selected unit must + agree exactly. + +Mode output +----------- + +``normal_modes_file`` stores the dimensionless Cartesian mode matrix. +``modes_prefix`` writes sinusoidal multi-frame XYZ animations, while +``modes_file`` writes one extended-XYZ image per selected mode with vectors and +metadata. Explicit mode numbers are one-based. + +See :ref:`analysis-output-vibrations` for every table and file schema. The main +entry point is :func:`PQAnalysis.analysis.vibrational.api.vibrations`; direct +calculations use +:func:`PQAnalysis.analysis.vibrational.vibrational_analysis.calculate_from_system`. diff --git a/docs/source/conf.py b/docs/source/conf.py index d7f93d0e..94aa9ca8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,43 +1,43 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +"""Sphinx configuration for the PQAnalysis documentation.""" import sys -import os +from pathlib import Path + + +SOURCE_DIR = Path(__file__).resolve().parent +DOCS_DIR = SOURCE_DIR.parent +PROJECT_ROOT = DOCS_DIR.parent -sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, str(PROJECT_ROOT)) -project = 'PQAnalysis' -copyright = '2023, Jakob Gamper, Josef M. Gallmetzer, Clarissa A. Seidler' -author = 'Jakob Gamper, Josef M. Gallmetzer, Clarissa A. Seidler' +project = "PQAnalysis" +author = "the PQAnalysis authors" +copyright = "2023-2026, the PQAnalysis authors" -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration +try: + from PQAnalysis import __version__ as release +except Exception: # pragma: no cover - package may be absent in a bare checkout + release = "" +version = release -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', - 'sphinx.ext.napoleon', - 'sphinx.ext.autosummary', - 'sphinx_sitemap', - 'sphinx.ext.inheritance_diagram', - 'myst_parser', + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.autosummary", + "sphinx.ext.inheritance_diagram", + "sphinx_sitemap", + "myst_parser", + "sphinx_copybutton", + "sphinx_design", ] -# Napoleon settings napoleon_google_docstring = True napoleon_numpy_docstring = True napoleon_include_init_with_doc = False @@ -50,92 +50,98 @@ napoleon_use_param = True napoleon_use_rtype = True -autoclass_content = 'both' -autodoc_class_signature = 'mixed' -autodoc_typehints_format = 'short' -autodoc_member_order = 'alphabetical' +autoclass_content = "both" +autodoc_class_signature = "mixed" +autodoc_typehints_format = "short" +autodoc_member_order = "alphabetical" maximum_signature_line_length = 50 add_module_names = False -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -source_suffix = ['.rst', '.md'] - -# The master toctree document. -master_doc = 'index' +copybutton_prompt_text = r">>> |\.\.\. |\$ " +copybutton_prompt_is_regexp = True -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path +templates_path = ["_templates"] +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} +master_doc = "index" exclude_patterns = [] +highlight_language = "python" -highlight_language = 'python' - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +html_theme = "furo" +html_title = "PQAnalysis" +html_logo = "logo/PQAnalysis.png" +html_favicon = "logo/PQAnalysis.png" +html_static_path = ["_static"] +html_css_files = ["css/custom.css"] +html_baseurl = "https://molarverse.github.io/PQAnalysis/" -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' -html_style = 'css/custom.css' html_theme_options = { - 'canonical_url': '', - 'analytics_id': '', # Provided by Google in your dashboard - 'prev_next_buttons_location': 'bottom', - 'style_external_links': False, - - 'logo_only': False, - - # Toc options - 'collapse_navigation': True, - 'sticky_navigation': True, - 'includehidden': True, - 'titles_only': True, - 'globaltoc_maxdepth': -1, + "sidebar_hide_name": False, + "light_css_variables": { + "color-brand-primary": "#1f718f", + "color-brand-content": "#176c8c", + }, + "dark_css_variables": { + "color-brand-primary": "#65bddb", + "color-brand-content": "#65bddb", + }, + "source_repository": "https://github.com/MolarVerse/PQAnalysis/", + "source_branch": "main", + "source_directory": "docs/source/", + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/MolarVerse/PQAnalysis", + "html": ( + '' + ), + "class": "", + }, + ], } -html_logo = 'logo/PQAnalysis.png' -# github_url = '' -html_baseurl = 'https://molarverse.github.io/PQAnalysis/' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - def show_inherited_mixins(app, what, name, obj, options, lines): - """Show inherited mixins in the base classes of a class""" + """Show inherited mixins in the base classes of a class.""" - if what != 'class' or not hasattr(obj, '__bases__'): + if what != "class" or not hasattr(obj, "__bases__"): return for base in obj.__bases__: - if base.__name__.endswith('Mixin'): - options['inherited-members'] = True + if base.__name__.endswith("Mixin"): + options["inherited-members"] = True def run_apidoc(app): - """Generage API documentation""" + """Generate the complete package API reference.""" import better_apidoc + better_apidoc.APP = app better_apidoc.main([ - 'better-apidoc', - '-t', - os.path.join('.', 'source', '_templates'), - '--force', - '--no-toc', - '--separate', - '-o', - os.path.join('.', 'source', 'code'), - os.path.join('..', 'PQAnalysis') + "better-apidoc", + "-t", + str(SOURCE_DIR / "_templates"), + "--force", + "--no-toc", + "--separate", + "-o", + str(SOURCE_DIR / "code"), + str(PROJECT_ROOT / "PQAnalysis"), ]) def setup(app): - app.connect('autodoc-process-docstring', show_inherited_mixins) - app.connect('builder-inited', run_apidoc) + app.connect("autodoc-process-docstring", show_inherited_mixins) + app.connect("builder-inited", run_apidoc) diff --git a/docs/source/data/index.rst b/docs/source/data/index.rst new file mode 100644 index 00000000..ad1e8fae --- /dev/null +++ b/docs/source/data/index.rst @@ -0,0 +1,88 @@ +Data and Conversion +=================== + +PQAnalysis separates simulation data, analysis configuration and output-table +serialization. File extensions select output formats, while input content and +explicit engine options determine how trajectories are read. + +.. grid:: 1 2 2 2 + :gutter: 2 + + .. grid-item-card:: Analysis input files + :link: ../userGuide/inputFile + :link-type: doc + + Key-value grammar, scalar values, lists and comments. + + .. grid-item-card:: Output tables + :link: ../userGuide/analysisOutputFiles + :link-type: doc + + Native metadata, CSV, TSV, XVG, columns, units and normalization. + + .. grid-item-card:: Command-line conversion + :link: ../reference/cli + :link-type: doc + + Convert analysis tables, structures, trajectories and box data. + + .. grid-item-card:: I/O API + :link: ../reference/api + :link-type: doc + + Readers, writers, formats and trajectory objects for Python workflows. + +Analysis configuration +---------------------- + +RDF, MSD, VACF and vibrational calculations use key-value input files. Lists +may be written in brackets or as multiline values according to the +:ref:`inputFile` grammar. Relative filenames are resolved by the process +running the command, so reproducible workflows should execute from a known run +directory. + +Trajectories and engines +------------------------ + +Analysis commands default to PQ conventions. Use ``--engine`` when reading a +supported alternative convention. Position analyses require coordinates and a +consistent atom count; MSD additionally needs periodic cells for unwrapping. +VACF and momentum analyses require velocity data. Molecular exclusions in RDF +require topology information from a restart and moldescriptor. + +The Python format definitions are documented by +:class:`PQAnalysis.traj.formats.MDEngineFormat` and +:class:`PQAnalysis.traj.formats.TrajectoryFormat`. + +Selections +---------- + +Analysis selections are parsed by :class:`PQAnalysis.topology.selection.Selection`. +Use elemental or atom-name selections for simple systems and full atom +information when residue-aware selection is required. Always verify that the +selection contains the intended atoms; normalization and statistical quality +depend directly on its population. + +Output and conversion +--------------------- + +Native, CSV, TSV and PQAnalysis-generated XVG tables are mutually convertible. +The converter detects input content rather than trusting the extension and can +write several outputs atomically: + +.. code-block:: console + + $ pqanalysis convert rdf.xvg \ + -o rdf.dat \ + -o rdf.csv \ + -o rdf.tsv + +No output is written if any requested destination already exists. Use +``--mode o`` only when intentional replacement is acceptable. + +.. toctree:: + :hidden: + :maxdepth: 1 + + Analysis input files <../userGuide/inputFile> + Analysis output files <../userGuide/analysisOutputFiles> diff --git a/docs/source/developerGuide/developerGuide.rst b/docs/source/developerGuide/developerGuide.rst index cb29d6ba..3c713511 100644 --- a/docs/source/developerGuide/developerGuide.rst +++ b/docs/source/developerGuide/developerGuide.rst @@ -1,117 +1,107 @@ .. _developerGuide: -############### -Developer Guide -############### +Development +=========== -This section includes information for developers who want to contribute to the project. It includes information about the project structure, how to run the tests, and how to build the documentation. It also includes information about the project's coding style and how to contribute to the project. +PQAnalysis uses a ``dev`` integration branch and releases from ``main``. +Feature and fix pull requests normally target ``dev``; release pull requests +merge ``dev`` into ``main``. -***************** -Coding Guidelines -***************** +Local setup +----------- -The project follows the `PEP8 `_ coding style. The project uses `setuptools `_ for packaging and distribution. The project uses `Sphinx `_ for documentation. The project uses `pytest `_ for testing. The project uses `Gitflow `_ for branching. +Clone the repository and install editable development, test and documentation +dependencies: -In order to contribute to the project, it is important to follow the coding style and guidelines used by the project, therefore please read ALL of the following sections carefully. +.. code-block:: console -***************** -How to Contribute -***************** + $ git clone https://github.com/MolarVerse/PQAnalysis.git + $ cd PQAnalysis + $ python -m venv .venv + $ source .venv/bin/activate + $ python -m pip install -e ".[dev,test,docs]" -For any contributor willing to contribute to the project, it is important to understand the branching model used by the project. The project uses the `Gitflow `_ branching model. Pull requests should stay small and reviewer-readable. In order to contribute to the project please follow the following steps: +Keep changes focused and add tests at the same ownership boundary as the +behavior being changed. +Tests +----- - #. Fork the project on Github. (not necessary if you are a member of the project) +The full test script runs the suite with runtime type checking enabled and +again with release settings: - #. Clone your fork locally: - - .. code:: bash +.. code-block:: console - $ git clone https://github.com/MolarVerse/PQAnalysis.git + $ bash pytest.sh - #. Initialize git flow with the following settings (if not specified default settings are used) +For a focused iteration, pass ordinary pytest arguments: - .. code:: bash +.. code-block:: console - [master] main - [develop] dev - [version tag prefix] v + $ bash pytest.sh tests/analysis/rdf -q - #. Create a feature branch for your contribution: - - .. code:: bash - - $ git flow feature start - - - #. Commit your changes to your feature branch and publish your feature branch: - - .. code:: bash - - $ git add - $ git commit -m "fix: describe the bug fix" - $ git flow feature publish - - #. Create a pull request on Github. - - #. Use a short Conventional Commits title for the pull request, for example ``feat: add a new analysis command`` or ``fix(io): handle missing trajectory data``. This title is validated by CI. - - #. Once your pull request is approved and all required checks pass, it will be merged into the develop branch. If the pull request is squash merged, use the pull request title as the squash commit message. - - #. Optional: enable the local commit-message hook for earlier feedback: - - .. code:: bash - - $ git config core.hooksPath .githooks - -************* Documentation -************* - -Please make sure that all code is well documented. The project uses `Sphinx `_ for documentation. The documentation of this webpage is autogenerated from the docstrings of the implemented code, thus it is important to make sure that all docstrings are correct and informative. - -.. attention:: - - The project uses `numpydoc `_ for docstring formatting. Please make sure that all docstrings are formatted correctly. +------------- -In order to install all the dependencies required for building the documentation, use the following command: +Build the complete documentation with warnings treated as errors: -.. code:: bash +.. code-block:: console - $ pip install -e ".[docs]" # install the project with the documentation dependencies + $ python -m sphinx -W --keep-going \ + -b html docs/source docs/build/html -To build the documentation, use the following command: +Check internal and external links separately: -.. code:: bash +.. code-block:: console - $ cd docs + $ python -m sphinx -W --keep-going \ + -b linkcheck docs/source docs/build/linkcheck - $ make html +The API reference is generated from package modules when Sphinx starts. Do not +hand-edit generated files under ``docs/source/code`` unless the generator or +its templates are being changed. User-facing scientific conventions belong in +the curated analysis, data and reference pages. -In order to view the documentation, open the following file in a web browser: +Documentation structure +----------------------- -.. code:: bash +* ``getting-started.rst`` provides the shortest working path. +* ``analyses/`` explains physical definitions, inputs and interpretation. +* ``data/`` covers file grammar, trajectories, selections and conversion. +* ``reference/`` indexes CLI and Python interfaces. +* ``userGuide/analysisOutputFiles.rst`` is the canonical output-schema source. +* ``code/`` is generated API material. - $ open build/html/index.html +Every analysis guide should state the physical quantity, assumptions, units, +minimal input, output fields and interpretation limits. Keep duplicated option +tables in generated API documentation rather than copying them into several +manual pages. -For the CI/CD pipeline, the a documentation coverage of 99.9% is required. Please make sure that all implemented features are correctly documented. To evaluate the documentation coverage, use the following command: +Pull requests +------------- -.. code:: bash +Pull requests should be reviewer-readable and use a Conventional Commits title, +for example ``feat: add a new analysis command`` or +``fix(io): handle missing trajectory data``. The repository validates the PR +title and uses it as the squash-merge commit message. - $ docstr-coverage PQAnalysis +The optional local commit-message hook provides earlier feedback: -******* -Testing -******* +.. code-block:: console -The project uses `pytest `_ for testing. Before creating a pull request, please make sure that all tests pass and ensure a high quality of code coverage. In order to run the tests, use the following command: + $ git config core.hooksPath .githooks -.. code:: bash +Before requesting review, run the focused tests for the change and every +relevant strict documentation build. CI publishes documentation only from +``main``; pull requests and ``dev`` pushes build it without deploying. - $ pip install -e ".[test]" # install the project with the test dependencies +Docstrings +---------- - $ python -m pytest +Public Python interfaces use NumPy-style docstrings. Document parameters, +returns, raised exceptions, units and array shapes precisely. Documentation +coverage can be inspected with: -The testing framework will run all tests and provide automatically generated coverage reports. Not only should all tests pass, but the coverage should be as close to 100% as possible. Furthermore, the project automatically uses doctest, so please make sure that all examples included in the doc strings of the implemented features are correct otherwise the tests will fail. +.. code-block:: console -Last, if any additional dependencies are required for testing, please add them to the ``pyproject.toml`` file under the ``[project.optional-dependencies]`` section. + $ docstr-coverage PQAnalysis diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst new file mode 100644 index 00000000..db13da67 --- /dev/null +++ b/docs/source/getting-started.rst @@ -0,0 +1,99 @@ +Getting Started +=============== + +Install PQAnalysis +------------------ + +PQAnalysis supports Python 3.12 and newer. Install the current release from +PyPI: + +.. code-block:: console + + $ python -m pip install pqanalysis + +Confirm that the command dispatcher and analysis commands are available: + +.. code-block:: console + + $ pqanalysis --help + $ pqanalysis rdf --help + +Run a first analysis +-------------------- + +Create ``rdf.in`` beside a PQ trajectory named ``trajectory.xyz``: + +.. code-block:: text + + traj_files = trajectory.xyz + reference_selection = O + target_selection = H + delta_r = 0.05 + out_file = rdf.dat + +Run the calculation: + +.. code-block:: console + + $ pqanalysis rdf rdf.in + +``rdf.dat`` contains the bin-center distance, radial distribution function, +cumulative coordination number, density-normalized shell population and +ideal-gas pair-count residual. Its commented metadata header records the field +names, scientific symbols and units. See :ref:`analysis-output-rdf` for the +exact definitions. + +Choose output formats +--------------------- + +The output filename selects the table format. ``.csv`` and ``.tsv`` open +directly in spreadsheet software, ``.xvg`` opens in xmgrace, and any other +extension uses native PQAnalysis text. + +Additional outputs do not require another analysis run: + +.. code-block:: console + + $ pqanalysis rdf rdf.in \ + --export rdf.csv \ + --export rdf.tsv \ + --export rdf.xvg + +Existing analysis tables can be converted later: + +.. code-block:: console + + $ pqanalysis convert rdf.dat -o rdf.csv -o rdf.xvg + +PQAnalysis refuses to overwrite an existing output unless replacement is +requested explicitly with ``--mode o``. + +Next steps +---------- + +.. grid:: 1 2 2 2 + :gutter: 2 + + .. grid-item-card:: Select an analysis + :link: analyses/index + :link-type: doc + + Compare structural, transport, spectral and diagnostic calculations. + + .. grid-item-card:: Input and data + :link: data/index + :link-type: doc + + Learn the input grammar, trajectory conventions and output formats. + + .. grid-item-card:: Command reference + :link: reference/cli + :link-type: doc + + Inspect every command, positional argument and optional flag. + + .. grid-item-card:: Python API + :link: reference/api + :link-type: doc + + Integrate analyses and readers into Python workflows. diff --git a/docs/source/index.rst b/docs/source/index.rst index 1580bbe1..dee90b6c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,23 +1,98 @@ -.. PQAnalysis documentation master file, created by - sphinx-quickstart on Mon Oct 23 16:52:21 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -########## PQAnalysis -########## +========== -.. toctree:: - :hidden: - :maxdepth: -1 - - userGuide/userGuide - developerGuide/developerGuide - code/PQAnalysis.rst +PQAnalysis provides command-line and Python tools for quantitative analysis of +PQ molecular-dynamics simulations. It reads structures, trajectories, +velocities and Hessians, then produces documented scientific tables for +structural, transport and vibrational observables. + +:doc:`Get started ` | :doc:`Choose an analysis ` | +:doc:`Work with data ` | :doc:`Command reference ` + +Quick start +----------- + +PQAnalysis requires Python 3.12 or newer. + +.. code-block:: console + + $ python -m pip install pqanalysis + $ pqanalysis rdf rdf.in + +The output filename in an analysis input file selects native text, CSV, TSV or +XVG. Repeat ``--export`` to write several formats in the same run. + +.. code-block:: console + + $ pqanalysis rdf rdf.in --export rdf.csv --export rdf.xvg + +Documentation +------------- + +.. grid:: 1 2 3 3 + :gutter: 2 + + .. grid-item-card:: Getting started + :link: getting-started + :link-type: doc + + Install PQAnalysis and run a first radial-distribution calculation. + + .. grid-item-card:: Analyses + :link: analyses/index + :link-type: doc -Welcome to PQAnalysis's documentation! -====================================== + RDF, MSD, VACF, spectra, normal modes and momentum diagnostics. -:ref:`userGuide` + .. grid-item-card:: Data and conversion + :link: data/index + :link-type: doc + + Input syntax, trajectories, selections and scientific table formats. + + .. grid-item-card:: Command line + :link: reference/cli + :link-type: doc + + Analysis, conversion and trajectory command reference. + + .. grid-item-card:: Python API + :link: reference/api + :link-type: doc + + Curated entry points and the complete generated package reference. + + .. grid-item-card:: Development + :link: developerGuide/developerGuide + :link-type: doc + + Branching, tests, documentation checks and contribution conventions. + +Scientific output +----------------- + +Native analysis tables retain their established numeric layout and add a +compact UTF-8 metadata header. Stable ASCII field names support scripts while +Unicode symbols and units describe the physical quantities. + +.. code-block:: text + + # PQAnalysis: Radial distribution function + # FIELDS r_i g_r_i N_r_i g_r_i_dV_i H_i_minus_E_i + # SYMBOLS rᵢ g(rᵢ) N(rᵢ) g(rᵢ)ΔVᵢ Hᵢ−Eᵢ + # UNITS Å 1 1 ų pairs + 0.5 0.0 0.0 0.0 -0.05026548245743666 + +See :ref:`analysisOutputFiles` for every column, normalization convention and +conversion path. + +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: Documentation -:ref:`developerGuide` + getting-started + analyses/index + data/index + reference/index + Development diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst new file mode 100644 index 00000000..71ca3973 --- /dev/null +++ b/docs/source/reference/api.rst @@ -0,0 +1,67 @@ +Python API +========== + +The public analysis wrappers accept the same input files as the command line +and are the simplest integration points: + +.. list-table:: Analysis entry points + :header-rows: 1 + :widths: 34 66 + + * - Function + - Purpose + * - :func:`PQAnalysis.analysis.rdf.api.rdf` + - Radial distribution analysis + * - :func:`PQAnalysis.analysis.msd.api.msd` + - Mean square displacement analysis + * - :func:`PQAnalysis.analysis.vacf.api.vacf` + - Velocity or charge-flux correlation analysis + * - :func:`PQAnalysis.analysis.vibrational.api.vibrations` + - Vibrational analysis from a structure and Hessian + * - :func:`PQAnalysis.analysis.momentum.api.check_momentum` + - Frame-resolved total linear momentum + +Package areas +------------- + +.. grid:: 1 2 3 3 + :gutter: 2 + + .. grid-item-card:: Analysis API + :link: ../code/PQAnalysis.analysis + :link-type: doc + + Calculations, input readers, result models and output writers. + + .. grid-item-card:: Input and output + :link: ../code/PQAnalysis.io + :link-type: doc + + Trajectory, restart, topology and simulation-file readers and writers. + + .. grid-item-card:: Trajectories + :link: ../code/PQAnalysis.traj + :link-type: doc + + Engine formats, trajectory containers and high-level operations. + + .. grid-item-card:: Atomic systems + :link: ../code/PQAnalysis.atomic_system + :link-type: doc + + Atomic coordinates, cells and topology-bearing systems. + + .. grid-item-card:: Topology and selection + :link: ../code/PQAnalysis.topology + :link-type: doc + + Selections, residues, bonded topology and SHAKE definitions. + + .. grid-item-card:: Complete package index + :link: ../code/PQAnalysis + :link-type: doc + + Every generated module, class, function and exception. + +Use the curated analysis guides for physical conventions and the generated +reference for signatures and implementation-level details. diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst new file mode 100644 index 00000000..5fa0688d --- /dev/null +++ b/docs/source/reference/cli.rst @@ -0,0 +1,96 @@ +Command-Line Reference +====================== + +``pqanalysis`` dispatches all supported commands from one executable. Every +subcommand also provides local help: + +.. code-block:: console + + $ pqanalysis --help + $ pqanalysis rdf --help + +Analysis commands +----------------- + +.. list-table:: Analysis commands + :class: pq-command-table + :header-rows: 1 + :widths: 24 50 26 + + * - Command + - Purpose + - Primary input + * - :ref:`rdf ` + - Radial distribution and cumulative coordination + - Input file + * - :ref:`msd ` + - Mean square displacement and diffusion fits + - Input file + * - :ref:`vacf ` + - Velocity or charge-flux correlation and spectra + - Input file + * - :ref:`vibrations ` + - Hessian normal modes and optional IR intensities + - Input file + * - :ref:`check_momentum ` + - Total linear momentum per velocity frame + - Trajectory files + * - :ref:`build_spectrum ` + - Gaussian or Lorentzian broadening of discrete lines + - Line table + +Analysis commands accept ``--export FILE`` where applicable. Repeat the option +to produce several output formats without repeating the calculation. + +Table conversion +---------------- + +``pqanalysis convert`` reads native, CSV, TSV or PQAnalysis-generated XVG +analysis tables and writes one or more target formats. It preserves complete +schemas and hidden XVG data sets. See +:doc:`the generated option reference <../code/PQAnalysis.cli.convert>`. + +Structure and trajectory conversion +----------------------------------- + +.. list-table:: Structure and trajectory commands + :class: pq-command-table + :header-rows: 1 + :widths: 28 72 + + * - Command + - Purpose + * - :ref:`rst2xyz ` + - Convert a PQ restart structure to XYZ + * - :ref:`xyz2rst ` + - Convert XYZ coordinates to a PQ restart structure + * - :ref:`xyz2gen ` + - Convert XYZ to DFTB+ GEN + * - :ref:`gen2xyz ` + - Convert DFTB+ GEN to XYZ + * - :ref:`traj2box ` + - Extract periodic box data from trajectories + * - :ref:`traj2extxyz ` + - Write extended XYZ trajectories with selected metadata + * - :ref:`traj2qmcfc ` + - Convert trajectories to QMCFC conventions + +Simulation-support commands +--------------------------- + +.. list-table:: Simulation-support commands + :class: pq-command-table + :header-rows: 1 + :widths: 28 72 + + * - Command + - Purpose + * - :ref:`continue_input ` + - Continue indexed PQ or QMCFC input/output sequences + * - :ref:`add_molecules ` + - Add molecular structures to an existing system + * - :ref:`build_nep_traj ` + - Assemble a trajectory from nudged-elastic-band data + +Commands refuse unsafe output replacement by default. Consult each generated +reference page for its supported writing modes and format-specific options. diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst new file mode 100644 index 00000000..239dd118 --- /dev/null +++ b/docs/source/reference/index.rst @@ -0,0 +1,34 @@ +Reference +========= + +Use the command reference for shell workflows and the Python API reference for +library integration. Scientific output definitions remain centralized so CLI +and API users share the same field names, units and normalization conventions. + +.. grid:: 1 2 3 3 + :gutter: 2 + + .. grid-item-card:: Command line + :link: cli + :link-type: doc + + Analysis, format-conversion and simulation-support commands. + + .. grid-item-card:: Python API + :link: api + :link-type: doc + + Curated public entry points and the complete package reference. + + .. grid-item-card:: Output schemas + :link: ../userGuide/analysisOutputFiles + :link-type: doc + + Stable fields, symbols, units and file-format behavior. + +.. toctree:: + :hidden: + :maxdepth: 1 + + cli + api diff --git a/docs/source/userGuide/analysisOutputFiles.rst b/docs/source/userGuide/analysisOutputFiles.rst index 076f00eb..4112a05e 100644 --- a/docs/source/userGuide/analysisOutputFiles.rst +++ b/docs/source/userGuide/analysisOutputFiles.rst @@ -1,8 +1,7 @@ .. _analysisOutputFiles: -##################### Analysis Output Files -##################### +===================== PQAnalysis analysis commands can write native text, CSV, TSV or XVG tables. The output filename selects the format: @@ -27,7 +26,7 @@ output filename selects the format: - Native PQAnalysis text - Self-describing scientific data and legacy workflows -This means that ``out_file table.csv`` in an RDF, MSD, VACF or vibrations input +This means that ``out_file = table.csv`` in an RDF, MSD, VACF or vibrations input file writes CSV directly. Names ending in ``.dat``, ``.out``, ``.txt`` or no extension retain the native format. diff --git a/docs/source/userGuide/inputFile.rst b/docs/source/userGuide/inputFile.rst index 3ea461cc..164f8525 100644 --- a/docs/source/userGuide/inputFile.rst +++ b/docs/source/userGuide/inputFile.rst @@ -1,50 +1,125 @@ .. _inputFile: -########## -Input File -########## +Analysis Input Files +==================== -The general parsing of the input file is based on a Lark grammar implementation (For more details see `Lark Grammar `_). Any input file must be based on the following definitions of input key and value pairs: +RDF, MSD, VACF and vibrational analyses use a compact key-value format parsed +with `Lark `_. Each analysis documents its +required and optional keys in the generated command and input-reader reference. -.. note:: - There are two different types of input key and value pairs. The first type is the key and value pairs that are defined in line seperated by a :code:`=` e.g: +Inline statements +----------------- - .. code-block:: bash - - key = value +An inline statement assigns one value to one key: - The second type are so called multiline statements where in the first line the key is defined and in the following lines the values assigned to the key. The multiline statements must be closed by an :code:`END` statement. The following example shows a multiline statement: +.. code-block:: text - .. code-block:: bash + key = value - key - value1 - value2 - END +Several assignments may share a line when separated by commas: - It is important to note that multiline statements are always parsed as list/array like values. This means, if the documentation of the key states that the value is not a list or array, an inlined statement must be used. +.. code-block:: text -.. note:: - In general, all keys are case-insensitive as well as the closing statement :code:`END` of a multiline statement. The values are case-sensitive. Furthermore, all keys and values are stripped from leading and trailing whitespaces and :code:`#` can be used to include comments (including inline comments). Inline statements using :code:`key = value` can also be used multiple times in one line separated by a :code:`,` to define multiple key and value pairs in one line e.g.: + window = 1000, gap = 10, time_step = 0.001 - .. code-block:: bash +Use separate lines for scientific input files unless a compact generated file +is required; one assignment per line is easier to review and diff. - key1 = value1, key2 = value2 +Multiline lists +--------------- -.. note:: - The values are read as strings and are converted to the correct type based on the documentation of the key (if possible). In general, the user should not worry about the type of the value as the parser will try to convert the value to the correct type. If the conversion fails, an error will be raised. The following examples show the conversion of the values: +A key followed by values on subsequent lines creates a list. Terminate the +list with ``END``: - * :code:`True` and :code:`False` are converted to :code:`bool` (case-insensitive) - * :code:`1` is converted to :code:`int` following possible conversions to :code:`float` - * :code:`1.0` is converted to :code:`float` - * :code:`any-kind-of_string` is converted to :code:`str` - * :code:`[1, 2, 3]` is converted to :code:`list` following possible (all values have to be of the same type) - * :code:`1..4` is converted to :code:`range` range(1, 4) - * :code:`1-4` same as :code:`1..4` - * :code:`1..3..10` is converted to :code:`range` range(1, 10, 3), please note that the step size is always the middle value in contrast to the python syntax - * :code:`1-3-10` same as :code:`1..3..10` - * :code:`file_0*.text` is treated as a list of files matching the pattern (For more details see the `glob package `_) +.. code-block:: text + traj_files + trajectory-001.xyz + trajectory-002.xyz + trajectory-003.xyz + END +Multiline syntax always produces a list-like value. Use inline syntax for keys +that accept only a scalar. +Comments and case +----------------- +Keys are case-insensitive. The closing ``END`` token must be uppercase. Values +remain case-sensitive because they may contain filenames or selection +expressions. Leading and trailing whitespace is ignored. ``#`` starts a +comment, including at the end of a statement: + +.. code-block:: text + + target_selection = O # oxygen atoms + +Value conversion +---------------- + +The parser converts strings to the type required by each documented key. +Common forms include: + +.. list-table:: Input value forms + :header-rows: 1 + :widths: 30 30 40 + + * - Input + - Parsed form + - Notes + * - ``True`` or ``False`` + - Boolean + - Case-insensitive + * - ``1`` + - Integer + - May also satisfy a real-valued key + * - ``1.0`` + - Floating-point number + - Scientific notation is accepted where numeric keys permit it + * - ``[1, 2, 3]`` + - List + - Elements must have compatible types + * - ``1..4`` or ``1-4`` + - ``range(1, 4)`` + - The stop value follows Python's exclusive convention + * - ``1..3..10`` or ``1-3-10`` + - ``range(1, 10, 3)`` + - The middle value is the step + * - ``frame-*.xyz`` + - Matching file list + - Expanded with Python glob semantics + +Filenames +--------- + +Relative filenames are interpreted from the command's working directory. The +ordinary filename grammar accepts letters, digits, ``_``, ``-`` and ``.``; +``*`` provides glob matching. For a portable analysis directory, keep the +input file and its referenced data together and run the command from that +directory. + +Complete example +---------------- + +.. code-block:: text + + # oxygen-hydrogen radial distribution + traj_files + run-001.xyz + run-002.xyz + END + + reference_selection = O + target_selection = H + delta_r = 0.05 + r_max = 8.0 + out_file = rdf.dat + +Run it with: + +.. code-block:: console + + $ pqanalysis rdf rdf.in + +See :doc:`../analyses/index` for analysis-specific examples and +:doc:`analysisOutputFiles` for output formats and scientific schemas. diff --git a/docs/source/userGuide/userGuide.rst b/docs/source/userGuide/userGuide.rst index 8e90e4ca..b40c8280 100644 --- a/docs/source/userGuide/userGuide.rst +++ b/docs/source/userGuide/userGuide.rst @@ -1,160 +1,35 @@ +:orphan: + .. _userGuide: -########## User Guide -########## - -.. toctree:: - :hidden: - :maxdepth: 1 - - inputFile - analysisOutputFiles - -Command Line Interface -====================== - -The PQAnalysis package does not only provide an API but also a number of different command line tools. These tools can be categorized into two groups primary groups: pure command line tools and tools that are based on an input file. - -Input file based tools ----------------------- - -For more details on the grammar and syntax of the input file see :ref:`inputFile`. -For the columns, units and normalization conventions of analysis output files, -see :ref:`analysisOutputFiles`. - -- :ref:`rdf` -- :ref:`msd` -- :ref:`vacf` -- :ref:`vibrations` - -RDF input files -^^^^^^^^^^^^^^^ - -Basic RDF calculations only need a trajectory, selections, bin settings, -and an output file. A restart file is not required for this case: - -.. code-block:: text - - reference_selection = H - target_selection = O - delta_r = 0.05 - out_file = rdf.out - traj_files = trajectory.xyz - -Restart files and moldescriptor files are only needed when the calculation -requires molecular topology information. For example, -:code:`no_intra_molecular = True` excludes pairs from the same molecule. -If the files are not given explicitly, PQAnalysis tries to infer -:code:`trajectory.rst` from :code:`trajectory.xyz` and -:code:`moldescriptor.dat` from the trajectory directory: - -.. code-block:: text - - reference_selection = H - target_selection = O - delta_r = 0.05 - out_file = rdf_inter.out - traj_files = trajectory.xyz - no_intra_molecular = True - -Explicit :code:`restart_file` and :code:`moldescriptor_file` values are used -as-is. If both files are given and :code:`no_intra_molecular` is omitted, -:code:`no_intra_molecular` defaults to :code:`True`. If -:code:`no_intra_molecular` is set to :code:`False`, intra molecular pairs are -included. Inferred and defaulted values are written to the normal PQAnalysis -log output. - -Vibrational analysis input files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Vibrational analyses use a structure file and a Cartesian Hessian matrix. The Hessian can be generated by a PQ ``mm-hessian`` run. - -.. code-block:: text - - structure_file = structure.rst - hessian_file = hessian.dat - moldescriptor_file = moldescriptor.dat - out_file = wavenumbers.dat - normal_modes_file = normal_modes.dat - modes_prefix = mode - modes_file = modes.xyz - modes = positive - modes_frames = 30 - modes_amplitude = 0.25 - modes_threshold = 1.0e-6 - unit = kcal - hessian_sign = auto - -The ``moldescriptor_file`` key is optional, but IR intensities require partial charges. ``unit`` accepts ``kcal``, ``hartree`` and ``ev``. ``hessian_sign = auto`` lets PQAnalysis choose the sign convention that gives the larger number of non-negative vibrational modes. - -Mode visualization is optional. ``modes_prefix`` writes one sinusoidal multi-frame XYZ animation per selected mode, for example ``mode-6.xyz``. ``modes_file`` writes one extended XYZ file with mode vectors and metadata, similar to ASE/Jmol vibration output. ``modes`` accepts ``all``, ``nonzero``, ``positive``, one mode number, a list of mode numbers or a range. Explicit mode numbers are one-based. ``modes_frames`` controls animation frames, ``modes_amplitude`` controls fixed-amplitude displacement in Angstrom, and ``modes_threshold`` filters named mode selections in ``cm-1``. ``modes_temperature`` can be used instead for ASE-style energy-scaled animations. - -MSD input files -^^^^^^^^^^^^^^^ - -Mean square displacement analyses compute the multiple-time-origin MSD of a -selected atom set with periodic-image unwrapping. If ``time_step`` (in ps) is -given, the self-diffusion coefficient is obtained from an Einstein-relation -fit over the trailing ``fit_window`` points and reported in the log output in -m\ :sup:`2`/s: - -.. code-block:: text +========== - traj_files = trajectory.xyz - target_selection = O - out_file = msd.dat - window = 1000 - gap = 10 - time_step = 0.001 - fit_window = 200 +The PQAnalysis user documentation is organized by task: -The output file contains the frame lag and the per-axis MSD in Angstrom -squared, matching the format of the legacy Diffcalc tool. ``window`` must be -divisible by ``gap``. +.. grid:: 1 2 2 2 + :gutter: 2 -VACF input files -^^^^^^^^^^^^^^^^ + .. grid-item-card:: Getting started + :link: ../getting-started + :link-type: doc -Velocity autocorrelation analyses read a velocity trajectory (``.vel``) and -compute the normalized VACF; with ``spectrum_file`` set, the windowed cosine -transform yields a vibrational power spectrum in cm\ :sup:`-1`: + Installation, first RDF calculation and output formats. -.. code-block:: text + .. grid-item-card:: Analyses + :link: ../analyses/index + :link-type: doc - traj_files = trajectory.vel - target_selection = all - out_file = vacf.dat - time_step = 0.001 - window = 2500 - gap = 5 - spectrum_file = spectrum.dat - ftsize = 5000 - window_function = exponential - window_param = 4.0 - window_start = 0.0 - window_stop = 1.0 + Scientific definitions, input examples and interpretation guidance. -Setting ``charge_file`` (static charges) or ``charge_files`` (a charge -trajectory read in lockstep) switches to the charge-flux autocorrelation -q\ :sub:`i`\ v\ :sub:`i`, whose spectrum approximates an infrared spectrum. -``window_function`` accepts ``exponential``, ``hann`` and ``blackman``; -``method = fft`` selects a faster dense-origin estimator instead of the -legacy-exact sliding-origin one. + .. grid-item-card:: Data and conversion + :link: ../data/index + :link-type: doc -Pure command line tools ------------------------ + Input grammar, trajectories, selections and scientific tables. -- :ref:`build_spectrum` -- :ref:`check_momentum` -- :ref:`continue_input` -- :ref:`rst2xyz` -- :ref:`traj2extxyz` -- :ref:`traj2qmcfc` -- :ref:`traj2box` + .. grid-item-card:: Reference + :link: ../reference/index + :link-type: doc -Note that :ref:`check_momentum` parses velocities in -single precision: reported momentum norms below roughly 1e-7 times the -scaled sum of m\ :sub:`i` \|v\ :sub:`i`\| are parsing noise rather than -physical center of mass drift (the legacy ``equipartition.jl`` tool parses -in double precision and resolves smaller drift). + Command-line options, Python APIs and output schemas. diff --git a/pyproject.toml b/pyproject.toml index 861260d0..4b9c2df8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,9 +44,11 @@ dev = [ "yapf", ] docs = [ - "sphinx>=7,<9", + "furo>=2024.8.6,<2027", + "sphinx>=8,<9", + "sphinx-copybutton>=0.5,<1", + "sphinx-design>=0.6,<1", "sphinx-sitemap", - "sphinx-rtd-theme", "breathe", "myst-parser", "better-apidoc", @@ -95,4 +97,6 @@ gen2xyz = "PQAnalysis.cli.gen2xyz:main" [project.urls] "Homepage" = "https://github.com/MolarVerse/PQAnalysis" +"Documentation" = "https://molarverse.github.io/PQAnalysis/" +"Repository" = "https://github.com/MolarVerse/PQAnalysis" "PQ" = "https://github.com/MolarVerse/PQ" From 9ef5ecd9a16009eb9c1c0a0519ba96fd4b8e1973 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 12:33:36 +0200 Subject: [PATCH 02/12] docs: refine scientific presentation --- docs/source/_plots/_style.py | 48 ++++++++++++ docs/source/_plots/msd.py | 50 +++++++++++++ docs/source/_plots/rdf.py | 73 +++++++++++++++++++ docs/source/_plots/vacf.py | 50 +++++++++++++ docs/source/_plots/vibrations.py | 73 +++++++++++++++++++ docs/source/_static/css/custom.css | 48 ++++++++++-- docs/source/_templates/package.rst | 2 +- docs/source/analyses/index.rst | 43 +---------- docs/source/analyses/msd.rst | 10 +++ docs/source/analyses/rdf.rst | 9 +++ docs/source/analyses/vacf.rst | 9 +++ docs/source/analyses/vibrations.rst | 9 +++ docs/source/conf.py | 8 +- docs/source/data/index.rst | 30 ++------ docs/source/developerGuide/developerGuide.rst | 7 +- docs/source/getting-started.rst | 31 ++------ docs/source/index.rst | 70 +++++++----------- docs/source/reference/api.rst | 60 +++++---------- docs/source/reference/index.rst | 24 +----- docs/source/userGuide/userGuide.rst | 32 ++------ pyproject.toml | 2 +- 21 files changed, 457 insertions(+), 231 deletions(-) create mode 100644 docs/source/_plots/_style.py create mode 100644 docs/source/_plots/msd.py create mode 100644 docs/source/_plots/rdf.py create mode 100644 docs/source/_plots/vacf.py create mode 100644 docs/source/_plots/vibrations.py diff --git a/docs/source/_plots/_style.py b/docs/source/_plots/_style.py new file mode 100644 index 00000000..6c2ebefe --- /dev/null +++ b/docs/source/_plots/_style.py @@ -0,0 +1,48 @@ +"""Shared Matplotlib style for the scientific documentation figures.""" + +from pathlib import Path + +import matplotlib as mpl + + +PROJECT_ROOT = Path(__file__).resolve().parents[3] + +COLORS = { + "blue": "#176c8c", + "green": "#008f72", + "orange": "#c7521c", + "magenta": "#a84d84", + "ink": "#202428", + "muted": "#66717a", + "grid": "#d7dde1", + "shell": "#dcecf2", +} + + +def apply_style(figsize: tuple[float, float]) -> None: + """Apply a restrained, colorblind-safe style to one figure.""" + + mpl.rcParams.update({ + "figure.figsize": figsize, + "figure.dpi": 120, + "figure.facecolor": "white", + "savefig.facecolor": "white", + "savefig.bbox": "tight", + "font.size": 9.5, + "axes.labelsize": 10, + "axes.labelcolor": COLORS["ink"], + "axes.edgecolor": COLORS["muted"], + "axes.linewidth": 0.8, + "axes.spines.top": False, + "axes.spines.right": False, + "axes.axisbelow": True, + "axes.grid": True, + "grid.color": COLORS["grid"], + "grid.linewidth": 0.7, + "grid.alpha": 0.8, + "xtick.color": COLORS["ink"], + "ytick.color": COLORS["ink"], + "legend.frameon": False, + "legend.fontsize": 8.5, + "lines.linewidth": 1.8, + }) diff --git a/docs/source/_plots/msd.py b/docs/source/_plots/msd.py new file mode 100644 index 00000000..a03a7343 --- /dev/null +++ b/docs/source/_plots/msd.py @@ -0,0 +1,50 @@ +"""MSD components and diffusion-fit interval from the validation fixture.""" + +import matplotlib.pyplot as plt +import numpy as np + +from _style import COLORS, PROJECT_ROOT, apply_style + + +apply_style((7.2, 4.3)) + +data = np.loadtxt(PROJECT_ROOT / "tests/data/msd/msd_ref_O.dat") +time = data[:, 0] * 0.5 +components = data[:, 1:4] +total = np.sum(components, axis=1) + +fit_start = len(time) - 20 +fit_coefficients = np.polyfit(time[fit_start:], total[fit_start:], 1) +fit = np.polyval(fit_coefficients, time[fit_start:]) + +figure, axis = plt.subplots() +for values, label, color in zip( + components.T, + (r"$\mathrm{MSD}_x$", r"$\mathrm{MSD}_y$", r"$\mathrm{MSD}_z$"), + (COLORS["blue"], COLORS["green"], COLORS["magenta"]), +): + axis.plot(time, values, color=color, linewidth=1.35, label=label) + +axis.plot(time, total, color=COLORS["ink"], linewidth=2.2, label="total") +axis.axvspan( + time[fit_start], + time[-1], + color=COLORS["shell"], + label="fit interval", +) +axis.plot( + time[fit_start:], + fit, + color=COLORS["orange"], + linestyle="--", + linewidth=1.7, + label="linear fit", +) +axis.set_xlabel(r"Lag time $t$ / ps") +axis.set_ylabel(r"Mean square displacement / $\mathrm{\AA}^2$") +axis.set_xlim(time[0], time[-1]) +axis.set_ylim(bottom=0.0) +axis.legend(ncol=3, loc="upper left") + +figure.tight_layout() +plt.show() diff --git a/docs/source/_plots/rdf.py b/docs/source/_plots/rdf.py new file mode 100644 index 00000000..f9ce3dee --- /dev/null +++ b/docs/source/_plots/rdf.py @@ -0,0 +1,73 @@ +"""Analytic RDF profile used to explain structural features.""" + +import matplotlib.pyplot as plt +import numpy as np + +from _style import COLORS, apply_style + + +apply_style((7.2, 5.0)) + +r = np.linspace(0.02, 8.0, 800) +excluded_volume = 1.0 - np.exp(-(r / 1.65)**8) +structure = ( + 1.0 + + 2.2 * np.exp(-0.5 * ((r - 2.80) / 0.22)**2) + - 0.55 * np.exp(-0.5 * ((r - 3.55) / 0.30)**2) + + 0.65 * np.exp(-0.5 * ((r - 4.65) / 0.38)**2) + - 0.18 * np.exp(-0.5 * ((r - 5.55) / 0.45)**2) +) +g_r = np.clip(excluded_volume * structure, 0.0, None) + +number_density = 0.0334 +coordination_integrand = 4.0 * np.pi * number_density * r**2 * g_r +coordination = np.concatenate(( + [0.0], + np.cumsum( + 0.5 + * (coordination_integrand[1:] + coordination_integrand[:-1]) + * np.diff(r) + ), +)) + +first_minimum = 3.55 +figure, (rdf_axis, coordination_axis) = plt.subplots( + 2, + 1, + sharex=True, + gridspec_kw={"height_ratios": (2.0, 1.25)}, +) + +rdf_axis.axvspan( + 0.0, + first_minimum, + color=COLORS["shell"], + label="first coordination shell", +) +rdf_axis.plot(r, g_r, color=COLORS["blue"]) +rdf_axis.axhline(1.0, color=COLORS["muted"], linestyle=":", linewidth=1.1) +rdf_axis.axvline( + first_minimum, + color=COLORS["orange"], + linestyle="--", + linewidth=1.2, + label="first minimum", +) +rdf_axis.set_ylabel(r"$g(r)$") +rdf_axis.set_ylim(0.0, 3.6) +rdf_axis.legend(loc="upper right") + +coordination_axis.plot(r, coordination, color=COLORS["orange"]) +coordination_axis.axvline( + first_minimum, + color=COLORS["orange"], + linestyle="--", + linewidth=1.2, +) +coordination_axis.set_xlabel(r"Distance $r$ / $\mathrm{\AA}$") +coordination_axis.set_ylabel(r"$N(r)$") +coordination_axis.set_xlim(0.0, 8.0) +coordination_axis.set_ylim(bottom=0.0) + +figure.tight_layout() +plt.show() diff --git a/docs/source/_plots/vacf.py b/docs/source/_plots/vacf.py new file mode 100644 index 00000000..80598b2e --- /dev/null +++ b/docs/source/_plots/vacf.py @@ -0,0 +1,50 @@ +"""VACF and Hann-window spectrum from the validation fixture.""" + +import matplotlib.pyplot as plt +import numpy as np + +from _style import COLORS, PROJECT_ROOT, apply_style + + +apply_style((7.2, 5.1)) + +correlation = np.loadtxt(PROJECT_ROOT / "tests/data/vacf/vacf_ref.dat") +spectrum = np.loadtxt( + PROJECT_ROOT / "tests/data/vacf/spectrum_hann_ref.dat" +) +spectrum = spectrum[spectrum[:, 0] <= 4000.0] + +figure, (correlation_axis, spectrum_axis) = plt.subplots( + 2, + 1, + gridspec_kw={"height_ratios": (1.25, 1.0)}, +) + +correlation_axis.plot( + correlation[:, 0], + correlation[:, 1], + color=COLORS["blue"], +) +correlation_axis.axhline( + 0.0, + color=COLORS["muted"], + linestyle=":", + linewidth=1.0, +) +correlation_axis.set_xlabel(r"Lag time $t$ / ps") +correlation_axis.set_ylabel(r"$C_v(t)$") +correlation_axis.set_xlim(correlation[0, 0], correlation[-1, 0]) +correlation_axis.set_ylim(-1.05, 1.05) + +spectrum_axis.plot( + spectrum[:, 0], + spectrum[:, 1], + color=COLORS["orange"], +) +spectrum_axis.set_xlabel(r"Wavenumber $\tilde{\nu}$ / $\mathrm{cm}^{-1}$") +spectrum_axis.set_ylabel("Amplitude / a.u.") +spectrum_axis.set_xlim(0.0, 4000.0) +spectrum_axis.set_ylim(bottom=0.0) + +figure.tight_layout() +plt.show() diff --git a/docs/source/_plots/vibrations.py b/docs/source/_plots/vibrations.py new file mode 100644 index 00000000..7bb50df2 --- /dev/null +++ b/docs/source/_plots/vibrations.py @@ -0,0 +1,73 @@ +"""IR stick spectrum calculated from the H2O validation fixture.""" + +import matplotlib.pyplot as plt +import numpy as np + +from PQAnalysis.analysis.vibrational.vibrational_analysis import ( + calculate_from_system, + read_hessian_file, +) +from PQAnalysis.io import MoldescriptorReader, RestartFileReader + +from _style import COLORS, PROJECT_ROOT, apply_style + + +apply_style((7.2, 3.8)) + +fixture = PROJECT_ROOT / "tests/data/vibrational" +moldescriptor = fixture / "moldescriptor.dat" +system = RestartFileReader( + str(fixture / "h2o.rst"), + moldescriptor_filename=str(moldescriptor), +).read() +hessian = read_hessian_file(str(fixture / "hessian.dat")) +charges = np.asarray( + MoldescriptorReader(str(moldescriptor)).read()[0].partial_charges, + dtype=float, +) +result = calculate_from_system( + system, + hessian, + atom_charges=charges, +) + +internal_modes = result.wavenumbers > 100.0 +wavenumbers = result.wavenumbers[internal_modes] +intensities = result.intensities[internal_modes] + +figure, axis = plt.subplots() +axis.vlines( + wavenumbers, + 0.0, + intensities, + color=COLORS["blue"], + linewidth=2.0, +) +axis.scatter( + wavenumbers, + intensities, + color=COLORS["blue"], + marker="_", + s=85, +) +for index, (wavenumber, intensity) in enumerate( + zip(wavenumbers, intensities) +): + axis.annotate( + f"{wavenumber:.0f}", + (wavenumber, intensity), + xytext=(0, 5 + 10 * (index % 2)), + textcoords="offset points", + ha="center", + va="bottom", + color=COLORS["ink"], + fontsize=8, + ) + +axis.set_xlabel(r"Wavenumber $\tilde{\nu}$ / $\mathrm{cm}^{-1}$") +axis.set_ylabel(r"IR intensity / $\mathrm{km\ mol}^{-1}$") +axis.set_xlim(0.0, 4200.0) +axis.set_ylim(0.0, max(intensities) * 1.22) + +figure.tight_layout() +plt.show() diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index a7e33447..affc1368 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -1,21 +1,57 @@ +:root { + --pq-plot-background: #fff; +} + +.sidebar-brand { + flex-direction: row; + align-items: center; + gap: 0.75rem; + padding-block: 0.75rem; +} + +.sidebar-logo-container { + display: flex; + flex: 0 0 4.5rem; + align-items: center; + margin: 0; +} + .sidebar-logo { - width: 4rem; + width: 4.5rem; + margin: 0; } .sidebar-brand-text { + margin: 0; + font-size: 1.35rem; font-weight: 700; + line-height: 1.1; letter-spacing: 0; } -.sd-card { - border-radius: 4px; - box-shadow: none; -} - code.literal { border-radius: 2px; } +figure:has(> img.plot-directive) { + margin-block: 1.5rem 2rem; +} + +img.plot-directive { + width: 100%; + height: auto; + border: 1px solid var(--color-foreground-border); + background: var(--pq-plot-background); +} + +img.plot-directive + figcaption { + margin-top: 0.65rem; + color: var(--color-foreground-secondary); + font-size: 0.9rem; + line-height: 1.45; + text-align: left; +} + .table-wrapper { overflow-x: auto; } diff --git a/docs/source/_templates/package.rst b/docs/source/_templates/package.rst index 195448b0..86c9a1c2 100644 --- a/docs/source/_templates/package.rst +++ b/docs/source/_templates/package.rst @@ -1,4 +1,4 @@ -{# Generated packages stay outside the curated user-facing navigation. #} +{# Generated packages stay outside the maintained user-facing navigation. #} :orphan: :autogenerated: diff --git a/docs/source/analyses/index.rst b/docs/source/analyses/index.rst index b5e891c4..6837b88f 100644 --- a/docs/source/analyses/index.rst +++ b/docs/source/analyses/index.rst @@ -6,45 +6,6 @@ time-correlation spectra, molecular normal modes and conservation diagnostics. Choose the observable from the physical question and from the data recorded by the simulation. -.. grid:: 1 2 3 3 - :gutter: 2 - - .. grid-item-card:: Radial distribution - :link: rdf - :link-type: doc - - Pair structure, preferred separations and coordination numbers. - - .. grid-item-card:: Mean square displacement - :link: msd - :link-type: doc - - Translational motion and Einstein-relation diffusion estimates. - - .. grid-item-card:: VACF and spectra - :link: vacf - :link-type: doc - - Velocity or charge-flux correlation and frequency-domain spectra. - - .. grid-item-card:: Vibrational analysis - :link: vibrations - :link-type: doc - - Hessian normal modes, wavenumbers, force constants and IR intensities. - - .. grid-item-card:: Total momentum - :link: momentum - :link-type: doc - - Frame-resolved linear momentum and center-of-mass drift diagnostics. - - .. grid-item-card:: Output schemas - :link: ../userGuide/analysisOutputFiles - :link-type: doc - - Exact columns, units, normalizations and format conversion behavior. - Choose by input data -------------------- @@ -71,6 +32,10 @@ Choose by input data - Velocities and atomic masses - :math:`|\sum_i m_i\mathbf{v}_i|` per frame +The method pages define each estimator, its assumptions and its interpretation +limits. File columns and units are specified once in +:ref:`analysisOutputFiles`. + .. toctree:: :hidden: :maxdepth: 1 diff --git a/docs/source/analyses/msd.rst b/docs/source/analyses/msd.rst index 8698a806..f755db50 100644 --- a/docs/source/analyses/msd.rst +++ b/docs/source/analyses/msd.rst @@ -13,6 +13,16 @@ origins according to Coordinates are unwrapped with the periodic cell before displacements are accumulated. +Estimator and fit interval +-------------------------- + +.. plot:: _plots/msd.py + :alt: Cartesian and total mean square displacement with a linear fit + :caption: Bundled oxygen-atom validation fixture with a 0.5 ps frame + interval. The dashed line fits the final 20 total-MSD samples and + illustrates fit-window selection; the fixture is not a material + diffusion benchmark. + Minimal input ------------- diff --git a/docs/source/analyses/rdf.rst b/docs/source/analyses/rdf.rst index 63809510..e99596fc 100644 --- a/docs/source/analyses/rdf.rst +++ b/docs/source/analyses/rdf.rst @@ -14,6 +14,15 @@ where :math:`H_i` is the eligible pair count, :math:`\rho_T` the target number density, :math:`N_R` the number of reference atoms, :math:`N_F` the number of frames and :math:`\Delta V_i` the spherical-shell volume. +Structural interpretation +------------------------- + +.. plot:: _plots/rdf.py + :alt: Radial distribution function and cumulative coordination number + :caption: Analytic schematic, not simulation output. The shaded interval + ends at the first minimum. The lower panel evaluates + N(r) = 4πρ∫₀ʳ g(s)s² ds with ρ = 0.0334 Å⁻³. + Minimal input ------------- diff --git a/docs/source/analyses/vacf.rst b/docs/source/analyses/vacf.rst index b4284dd2..42bcb270 100644 --- a/docs/source/analyses/vacf.rst +++ b/docs/source/analyses/vacf.rst @@ -15,6 +15,15 @@ static or time-dependent partial charges are supplied, it correlates :math:`q_i\mathbf{v}_i` instead, producing a charge-flux spectrum that approximates an infrared spectrum. +Correlation and spectrum +------------------------ + +.. plot:: _plots/vacf.py + :alt: Velocity autocorrelation function and its Hann-window spectrum + :caption: Bundled VACF validation fixture and its Hann-window cosine + transform. Spectrum amplitudes are reported in arbitrary units; the + displayed range is limited to 4000 cm⁻¹. + Minimal input ------------- diff --git a/docs/source/analyses/vibrations.rst b/docs/source/analyses/vibrations.rst index fb05df81..1421b705 100644 --- a/docs/source/analyses/vibrations.rst +++ b/docs/source/analyses/vibrations.rst @@ -6,6 +6,15 @@ eigenvectors define normal modes and its eigenvalues determine signed wavenumbers. Negative wavenumbers represent imaginary modes associated with negative curvature of the potential-energy surface. +Internal-mode spectrum +---------------------- + +.. plot:: _plots/vibrations.py + :alt: Infrared stick spectrum for the water validation fixture + :caption: IR stick spectrum calculated by PQAnalysis from the bundled H₂O + structure, Hessian and partial-charge fixtures. Only internal modes above + 100 cm⁻¹ are shown; translational and rotational modes are omitted. + Minimal input ------------- diff --git a/docs/source/conf.py b/docs/source/conf.py index 94aa9ca8..cb0911fc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,6 +10,7 @@ PROJECT_ROOT = DOCS_DIR.parent sys.path.insert(0, str(PROJECT_ROOT)) +sys.path.insert(0, str(SOURCE_DIR / "_plots")) project = "PQAnalysis" author = "the PQAnalysis authors" @@ -33,9 +34,9 @@ "sphinx.ext.autosummary", "sphinx.ext.inheritance_diagram", "sphinx_sitemap", + "matplotlib.sphinxext.plot_directive", "myst_parser", "sphinx_copybutton", - "sphinx_design", ] napoleon_google_docstring = True @@ -60,6 +61,11 @@ copybutton_prompt_text = r">>> |\.\.\. |\$ " copybutton_prompt_is_regexp = True +plot_formats = [("svg", 96)] +plot_html_show_formats = False +plot_html_show_source_link = False +plot_include_source = False + templates_path = ["_templates"] source_suffix = { ".rst": "restructuredtext", diff --git a/docs/source/data/index.rst b/docs/source/data/index.rst index ad1e8fae..41df11aa 100644 --- a/docs/source/data/index.rst +++ b/docs/source/data/index.rst @@ -5,32 +5,12 @@ PQAnalysis separates simulation data, analysis configuration and output-table serialization. File extensions select output formats, while input content and explicit engine options determine how trajectories are read. -.. grid:: 1 2 2 2 - :gutter: 2 +This section covers four interfaces: - .. grid-item-card:: Analysis input files - :link: ../userGuide/inputFile - :link-type: doc - - Key-value grammar, scalar values, lists and comments. - - .. grid-item-card:: Output tables - :link: ../userGuide/analysisOutputFiles - :link-type: doc - - Native metadata, CSV, TSV, XVG, columns, units and normalization. - - .. grid-item-card:: Command-line conversion - :link: ../reference/cli - :link-type: doc - - Convert analysis tables, structures, trajectories and box data. - - .. grid-item-card:: I/O API - :link: ../reference/api - :link-type: doc - - Readers, writers, formats and trajectory objects for Python workflows. +* :ref:`inputFile` defines the key-value grammar. +* :ref:`analysisOutputFiles` defines table fields, symbols and units. +* :doc:`../reference/cli` documents table, structure and trajectory conversion. +* :doc:`../reference/api` identifies readers, writers and trajectory objects. Analysis configuration ---------------------- diff --git a/docs/source/developerGuide/developerGuide.rst b/docs/source/developerGuide/developerGuide.rst index 3c713511..13f1d547 100644 --- a/docs/source/developerGuide/developerGuide.rst +++ b/docs/source/developerGuide/developerGuide.rst @@ -60,13 +60,15 @@ Check internal and external links separately: The API reference is generated from package modules when Sphinx starts. Do not hand-edit generated files under ``docs/source/code`` unless the generator or its templates are being changed. User-facing scientific conventions belong in -the curated analysis, data and reference pages. +the maintained analysis, data and reference pages. Documentation structure ----------------------- * ``getting-started.rst`` provides the shortest working path. * ``analyses/`` explains physical definitions, inputs and interpretation. +* ``_plots/`` contains executable Matplotlib figures built from documented + analytic models or versioned validation fixtures. * ``data/`` covers file grammar, trajectories, selections and conversion. * ``reference/`` indexes CLI and Python interfaces. * ``userGuide/analysisOutputFiles.rst`` is the canonical output-schema source. @@ -75,7 +77,8 @@ Documentation structure Every analysis guide should state the physical quantity, assumptions, units, minimal input, output fields and interpretation limits. Keep duplicated option tables in generated API documentation rather than copying them into several -manual pages. +manual pages. Figure captions must identify their data source and distinguish +analytic schematics, validation fixtures and physical benchmark results. Pull requests ------------- diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index db13da67..be5ba7aa 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -71,29 +71,8 @@ requested explicitly with ``--mode o``. Next steps ---------- -.. grid:: 1 2 2 2 - :gutter: 2 - - .. grid-item-card:: Select an analysis - :link: analyses/index - :link-type: doc - - Compare structural, transport, spectral and diagnostic calculations. - - .. grid-item-card:: Input and data - :link: data/index - :link-type: doc - - Learn the input grammar, trajectory conventions and output formats. - - .. grid-item-card:: Command reference - :link: reference/cli - :link-type: doc - - Inspect every command, positional argument and optional flag. - - .. grid-item-card:: Python API - :link: reference/api - :link-type: doc - - Integrate analyses and readers into Python workflows. +* :doc:`analyses/index` compares the physical observables and required data. +* :doc:`data/index` defines input grammar, trajectory conventions and table + formats. +* :doc:`reference/cli` lists commands and options. +* :doc:`reference/api` identifies the Python analysis and I/O entry points. diff --git a/docs/source/index.rst b/docs/source/index.rst index dee90b6c..f34610a5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,47 +26,31 @@ XVG. Repeat ``--export`` to write several formats in the same run. $ pqanalysis rdf rdf.in --export rdf.csv --export rdf.xvg -Documentation -------------- - -.. grid:: 1 2 3 3 - :gutter: 2 - - .. grid-item-card:: Getting started - :link: getting-started - :link-type: doc - - Install PQAnalysis and run a first radial-distribution calculation. - - .. grid-item-card:: Analyses - :link: analyses/index - :link-type: doc - - RDF, MSD, VACF, spectra, normal modes and momentum diagnostics. - - .. grid-item-card:: Data and conversion - :link: data/index - :link-type: doc - - Input syntax, trajectories, selections and scientific table formats. - - .. grid-item-card:: Command line - :link: reference/cli - :link-type: doc - - Analysis, conversion and trajectory command reference. - - .. grid-item-card:: Python API - :link: reference/api - :link-type: doc - - Curated entry points and the complete generated package reference. - - .. grid-item-card:: Development - :link: developerGuide/developerGuide - :link-type: doc - - Branching, tests, documentation checks and contribution conventions. +Analysis methods +---------------- + +.. list-table:: Implemented observables + :header-rows: 1 + :widths: 24 38 38 + + * - Method + - Required data + - Reported quantity + * - :doc:`Radial distribution ` + - Positions and periodic cell + - :math:`g_{AB}(r)` and cumulative coordination + * - :doc:`Mean square displacement ` + - Positions and periodic cell + - Cartesian MSD and diffusion fits + * - :doc:`VACF and spectra ` + - Velocities, sampling interval and optional charges + - Normalized correlation and wavenumber spectrum + * - :doc:`Vibrational analysis ` + - Structure, masses and Cartesian Hessian + - Normal modes, wavenumbers and optional IR intensities + * - :doc:`Momentum diagnostic ` + - Velocities and atomic masses + - Frame-resolved total linear momentum Scientific output ----------------- @@ -83,8 +67,8 @@ Unicode symbols and units describe the physical quantities. # UNITS Å 1 1 ų pairs 0.5 0.0 0.0 0.0 -0.05026548245743666 -See :ref:`analysisOutputFiles` for every column, normalization convention and -conversion path. +See :ref:`analysisOutputFiles` for column definitions, normalization +conventions and conversion behavior. .. toctree:: :hidden: diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index 71ca3973..63665570 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -24,44 +24,24 @@ and are the simplest integration points: Package areas ------------- -.. grid:: 1 2 3 3 - :gutter: 2 - - .. grid-item-card:: Analysis API - :link: ../code/PQAnalysis.analysis - :link-type: doc - - Calculations, input readers, result models and output writers. - - .. grid-item-card:: Input and output - :link: ../code/PQAnalysis.io - :link-type: doc - - Trajectory, restart, topology and simulation-file readers and writers. - - .. grid-item-card:: Trajectories - :link: ../code/PQAnalysis.traj - :link-type: doc - - Engine formats, trajectory containers and high-level operations. - - .. grid-item-card:: Atomic systems - :link: ../code/PQAnalysis.atomic_system - :link-type: doc - - Atomic coordinates, cells and topology-bearing systems. - - .. grid-item-card:: Topology and selection - :link: ../code/PQAnalysis.topology - :link-type: doc - - Selections, residues, bonded topology and SHAKE definitions. - - .. grid-item-card:: Complete package index - :link: ../code/PQAnalysis - :link-type: doc - - Every generated module, class, function and exception. +.. list-table:: Generated package reference + :header-rows: 1 + :widths: 34 66 -Use the curated analysis guides for physical conventions and the generated -reference for signatures and implementation-level details. + * - Package + - Scope + * - :doc:`Analysis <../code/PQAnalysis.analysis>` + - Calculations, input readers, result models and output writers + * - :doc:`Input and output <../code/PQAnalysis.io>` + - Trajectory, restart, topology and simulation-file readers and writers + * - :doc:`Trajectories <../code/PQAnalysis.traj>` + - Engine formats, trajectory containers and high-level operations + * - :doc:`Atomic systems <../code/PQAnalysis.atomic_system>` + - Coordinates, cells and topology-bearing systems + * - :doc:`Topology and selection <../code/PQAnalysis.topology>` + - Selections, residues, bonded topology and SHAKE definitions + * - :doc:`Package index <../code/PQAnalysis>` + - Generated module hierarchy + +Use the analysis guides for physical conventions and the generated reference +for signatures and implementation details. diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 239dd118..8c7373ed 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -5,26 +5,10 @@ Use the command reference for shell workflows and the Python API reference for library integration. Scientific output definitions remain centralized so CLI and API users share the same field names, units and normalization conventions. -.. grid:: 1 2 3 3 - :gutter: 2 - - .. grid-item-card:: Command line - :link: cli - :link-type: doc - - Analysis, format-conversion and simulation-support commands. - - .. grid-item-card:: Python API - :link: api - :link-type: doc - - Curated public entry points and the complete package reference. - - .. grid-item-card:: Output schemas - :link: ../userGuide/analysisOutputFiles - :link-type: doc - - Stable fields, symbols, units and file-format behavior. +* :doc:`cli` covers analysis, conversion and simulation-support commands. +* :doc:`api` lists public analysis functions and generated package modules. +* :ref:`analysisOutputFiles` specifies table fields, symbols, units and + serialization formats. .. toctree:: :hidden: diff --git a/docs/source/userGuide/userGuide.rst b/docs/source/userGuide/userGuide.rst index b40c8280..de7e2886 100644 --- a/docs/source/userGuide/userGuide.rst +++ b/docs/source/userGuide/userGuide.rst @@ -5,31 +5,9 @@ User Guide ========== -The PQAnalysis user documentation is organized by task: +This compatibility page points to the current task-oriented documentation: -.. grid:: 1 2 2 2 - :gutter: 2 - - .. grid-item-card:: Getting started - :link: ../getting-started - :link-type: doc - - Installation, first RDF calculation and output formats. - - .. grid-item-card:: Analyses - :link: ../analyses/index - :link-type: doc - - Scientific definitions, input examples and interpretation guidance. - - .. grid-item-card:: Data and conversion - :link: ../data/index - :link-type: doc - - Input grammar, trajectories, selections and scientific tables. - - .. grid-item-card:: Reference - :link: ../reference/index - :link-type: doc - - Command-line options, Python APIs and output schemas. +* :doc:`../getting-started`: installation, first RDF calculation and outputs +* :doc:`../analyses/index`: estimators, assumptions and interpretation +* :doc:`../data/index`: input grammar, trajectories and scientific tables +* :doc:`../reference/index`: command-line and Python interfaces diff --git a/pyproject.toml b/pyproject.toml index 4b9c2df8..e9a0c594 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,9 +45,9 @@ dev = [ ] docs = [ "furo>=2024.8.6,<2027", + "matplotlib>=3.9,<4", "sphinx>=8,<9", "sphinx-copybutton>=0.5,<1", - "sphinx-design>=0.6,<1", "sphinx-sitemap", "breathe", "myst-parser", From 887af1d10e8545cb1c91fa20e44a7ec42832d689 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 13:27:21 +0200 Subject: [PATCH 03/12] docs: expose developer interfaces --- PQAnalysis/io/restart_file/api.py | 2 +- README.md | 18 ++- docs/source/_static/css/custom.css | 103 ++++++++++++ docs/source/analyses/index.rst | 4 +- docs/source/data/index.rst | 4 +- .../source/developerGuide/adding-analysis.rst | 103 ++++++++++++ docs/source/developerGuide/architecture.rst | 89 +++++++++++ docs/source/developerGuide/developerGuide.rst | 146 ++++++++++-------- docs/source/developerGuide/release.rst | 72 +++++++++ docs/source/developerGuide/validation.rst | 91 +++++++++++ docs/source/getting-started.rst | 6 +- docs/source/index.rst | 53 ++++--- docs/source/reference/api.rst | 46 +++--- docs/source/reference/functions.rst | 84 ++++++++++ docs/source/reference/index.rst | 12 +- docs/source/userGuide/userGuide.rst | 4 +- 16 files changed, 713 insertions(+), 124 deletions(-) create mode 100644 docs/source/developerGuide/adding-analysis.rst create mode 100644 docs/source/developerGuide/architecture.rst create mode 100644 docs/source/developerGuide/release.rst create mode 100644 docs/source/developerGuide/validation.rst create mode 100644 docs/source/reference/functions.rst diff --git a/PQAnalysis/io/restart_file/api.py b/PQAnalysis/io/restart_file/api.py index 7d49d9c1..6d8b1e31 100644 --- a/PQAnalysis/io/restart_file/api.py +++ b/PQAnalysis/io/restart_file/api.py @@ -62,7 +62,7 @@ def write_restart_file( mode: FileWritingMode | str = 'w' ) -> None: """ - API function for reading a restart file. + Write an atomic system to a restart file. Parameters ---------- diff --git a/README.md b/README.md index bd4da712..20965f3b 100644 --- a/README.md +++ b/README.md @@ -19,18 +19,24 @@ Install with pip: ## Development -Clone the PQAnalysis GitHub repository and navigate into the directory: +Clone the repository and install the development, test and documentation +dependencies in an isolated environment: git clone https://github.com/MolarVerse/PQAnalysis.git cd PQAnalysis + python -m venv .venv + source .venv/bin/activate + python -m pip install -e ".[dev,test,docs]" -Install in editable mode with test dependencies: +Run the test suite with both debug and release runtime type checking: - pip install -e ".[test]" + bash pytest.sh -Run the test suite: - - python -m pytest +The [developer documentation](https://molarverse.github.io/PQAnalysis/developerGuide/developerGuide.html) +covers package architecture, adding an analysis, scientific validation and the +tag-driven release process. The +[function index](https://molarverse.github.io/PQAnalysis/reference/functions.html) +lists the supported Python entry points directly. Use squash merges for pull requests. The pull request title becomes the commit message on the target branch, so PR titles must follow diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index affc1368..1f65228e 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -56,6 +56,109 @@ img.plot-directive + figcaption { overflow-x: auto; } +@media (max-width: 44rem) { + article table.autosummary, + article table.pq-record-table { + display: block; + width: 100%; + } + + table.autosummary, + table.autosummary tbody, + table.autosummary tr, + table.autosummary td, + table.pq-record-table, + table.pq-record-table tbody, + table.pq-record-table tr, + table.pq-record-table td { + display: block; + width: 100%; + } + + table.autosummary, + table.pq-record-table { + border: 0; + } + + table.autosummary tr, + table.pq-record-table tr { + padding-block: 0.7rem; + border-bottom: 1px solid var(--color-foreground-border); + } + + table.autosummary td, + table.pq-record-table td { + padding: 0.2rem 0; + border: 0; + } + + table.autosummary td:first-child, + table.pq-record-table td:first-child { + font-weight: 650; + } + + table.autosummary td:last-child { + color: var(--color-foreground-secondary); + } + + table.pq-record-table thead { + display: none; + } + + table.pq-record-table td:not(:first-child)::before { + display: block; + margin-top: 0.35rem; + color: var(--color-foreground-secondary); + font-size: 0.75rem; + font-weight: 650; + text-transform: uppercase; + } + + table.pq-method-table td:nth-child(2)::before, + table.pq-observable-table td:nth-child(2)::before { + content: "Required data"; + } + + table.pq-method-table td:nth-child(3)::before, + table.pq-observable-table td:nth-child(3)::before { + content: "Reported quantity"; + } + + table.pq-extension-table td:nth-child(2)::before { + content: "Primary location"; + } + + table.pq-extension-table td:nth-child(3)::before { + content: "Contract"; + } + + table.pq-package-table td:nth-child(2)::before { + content: "Responsibility"; + } + + table.pq-validation-table td:nth-child(2)::before { + content: "Purpose"; + } + + table.pq-validation-table td:nth-child(3)::before { + content: "Suitable reference"; + } + + table.pq-types-table td:nth-child(2)::before { + content: "Role"; + } + + table.pq-package-reference-table td:nth-child(2)::before { + content: "Scope"; + } +} + +@media (max-width: 24rem) { + article h1 { + font-size: 2rem; + } +} + table.analysis-output-columns { min-width: 640px; width: 100%; diff --git a/docs/source/analyses/index.rst b/docs/source/analyses/index.rst index 6837b88f..481e54e8 100644 --- a/docs/source/analyses/index.rst +++ b/docs/source/analyses/index.rst @@ -10,6 +10,7 @@ Choose by input data -------------------- .. list-table:: Analysis inputs and primary observables + :class: pq-record-table pq-observable-table :header-rows: 1 :widths: 24 32 44 @@ -34,7 +35,8 @@ Choose by input data The method pages define each estimator, its assumptions and its interpretation limits. File columns and units are specified once in -:ref:`analysisOutputFiles`. +:ref:`analysisOutputFiles`. Programmatic entry points are listed in the +:doc:`../reference/functions`. .. toctree:: :hidden: diff --git a/docs/source/data/index.rst b/docs/source/data/index.rst index 41df11aa..f6a2c24b 100644 --- a/docs/source/data/index.rst +++ b/docs/source/data/index.rst @@ -1,5 +1,5 @@ -Data and Conversion -=================== +Files and Formats +================= PQAnalysis separates simulation data, analysis configuration and output-table serialization. File extensions select output formats, while input content and diff --git a/docs/source/developerGuide/adding-analysis.rst b/docs/source/developerGuide/adding-analysis.rst new file mode 100644 index 00000000..00426479 --- /dev/null +++ b/docs/source/developerGuide/adding-analysis.rst @@ -0,0 +1,103 @@ +Adding an Analysis +================== + +Use an existing complete analysis, such as RDF or MSD, as the structural +reference. Keep the scientific estimator independent from its CLI and file +format adapters. + +1. Define the scientific contract +--------------------------------- + +State the observable, normalization, units, periodic-boundary treatment, +selection semantics and returned array shapes before implementing the +calculation. Decide which behavior reproduces a legacy tool and which behavior +is a corrected or newly defined method. + +The analysis guide and tests must use the same definitions. A numerical result +without its normalization and units is not a complete interface. + +2. Implement the analysis package +--------------------------------- + +A file-driven analysis typically owns these modules: + +.. code-block:: text + + PQAnalysis/analysis// + __init__.py + api.py + .py + _input_file_reader.py + _output_file_writer.py + exceptions.py + +The analysis class or numerical function owns the calculation. The input reader +validates configuration and the writer serializes results. Avoid importing CLI +code from the analysis package. + +If a compiled kernel is required, provide a Python or NumPy fallback with the +same callable signature. Import the compiled implementation first and fall back +only when it is unavailable, following the RDF, MSD and VACF packages. + +3. Define inputs and outputs +---------------------------- + +Add input keys to the analysis input reader with explicit types, defaults and +validation. Required files should be validated before the trajectory is +processed. Keep aliases only when they preserve an established input contract. + +Define output columns in ``PQAnalysis/analysis/_output_schemas.py`` using +:class:`~PQAnalysis.analysis.output.AnalysisColumn` and +:class:`~PQAnalysis.analysis.output.AnalysisSchema`. Field identifiers are ASCII +programmatic names; symbols and units may use Unicode scientific notation. + +The data writer should subclass +:class:`~PQAnalysis.analysis.output.AnalysisDataWriter`, create an +:class:`~PQAnalysis.analysis.output.AnalysisTable` from the numerical columns, +and delegate CSV, TSV and XVG exports to the common writer. Preserve a legacy +native row format only when compatibility requires it. + +4. Add the public API +--------------------- + +The function in ``api.py`` is the shared orchestration layer. It should: + +1. read and validate the analysis input; +2. construct trajectory, structure or Hessian readers; +3. construct every output writer so path conflicts fail early; +4. instantiate and run the scientific analysis; +5. write the result and return useful in-memory data where appropriate. + +Export the function and supported result types from the analysis package +``__init__.py`` and, for a general analysis workflow, from +``PQAnalysis.analysis``. Add the callable to :doc:`../reference/functions`. + +5. Add the CLI +-------------- + +Implement a ``CLIBase`` subclass in ``PQAnalysis/cli/.py``. Its +``add_arguments`` method defines only command-line parsing; ``run`` calls the +public API function. Reuse common arguments from +``PQAnalysis/cli/_argument_parser.py``, including repeatable ``--export`` for +analysis tables. + +Register the class in the dispatch dictionary in ``PQAnalysis/cli/main.py``. +Add a ``[project.scripts]`` entry in ``pyproject.toml`` only when a standalone +executable is part of the supported interface. + +6. Add evidence and documentation +--------------------------------- + +The minimum complete change includes: + +* analytical or independently computed numerical tests; +* legacy parity tests when compatibility is claimed; +* compiled-kernel and fallback parity where both exist; +* input-reader validation and default tests; +* API and CLI end-to-end tests; +* native output and CSV, TSV and XVG tests; +* existing-file failure tests for every output path; +* an analysis page defining equations, assumptions, inputs and interpretation; +* entries in the function index, command reference and output-schema page. + +Follow :doc:`validation` for reference-data provenance and tolerance rules. diff --git a/docs/source/developerGuide/architecture.rst b/docs/source/developerGuide/architecture.rst new file mode 100644 index 00000000..cb616ee6 --- /dev/null +++ b/docs/source/developerGuide/architecture.rst @@ -0,0 +1,89 @@ +Architecture +============ + +PQAnalysis separates scientific computation from file orchestration. An +input-file analysis normally follows this path: + +.. code-block:: text + + CLI class + -> public API function + -> analysis input reader + -> trajectory, structure or Hessian reader + -> analysis object and numerical kernel + -> AnalysisTable with an AnalysisSchema + -> native writer and optional CSV, TSV or XVG writers + +The command line and Python API therefore share the calculation, validation and +output code. A CLI class should parse arguments and call a public API function; +it should not contain a second implementation of the scientific method. + +Package boundaries +------------------ + +.. list-table:: Source ownership + :class: pq-record-table pq-package-table + :header-rows: 1 + :widths: 30 70 + + * - Path + - Responsibility + * - ``PQAnalysis/analysis/`` + - Scientific estimators, spectra, result models and analysis-table output + * - ``PQAnalysis/cli/`` + - Argument definitions and dispatch to public API functions + * - ``PQAnalysis/io/`` + - Simulation-file readers, writers and format conversion + * - ``PQAnalysis/traj/`` + - Trajectory containers, engine formats and trajectory-wide checks + * - ``PQAnalysis/atomic_system/`` and ``PQAnalysis/core/`` + - Atomic coordinates, cells, atoms and residues + * - ``PQAnalysis/topology/`` + - Selections, molecular identity and bonded topology + +The :doc:`../reference/functions` page lists callable entry points. The +:doc:`../reference/api` page exposes the classes and generated modules behind +them. + +Public contracts +---------------- + +Treat the following as compatibility surfaces: + +* non-underscored functions and classes deliberately imported by a package + ``__init__.py``; +* command names, arguments and input-file keys; +* analysis result attributes and array shapes; +* output field identifiers, symbols, units and column order; +* accepted trajectory and structure formats; +* exception types raised for invalid user input. + +Modules, functions and attributes beginning with an underscore are internal. +Changing a public contract requires tests, documentation and either backward +compatibility or an explicit deprecation path. + +Numerical kernels +----------------- + +RDF, MSD and VACF use compiled Cython kernels when available and NumPy/Python +fallbacks otherwise. The compiled and fallback implementations must keep the +same signature, normalization and edge-case behavior. A kernel change therefore +requires tests of both implementations and a direct parity test between them. + +File parsing and logging belong outside numerical kernels. Kernels should accept +validated arrays and scalar parameters and return numerical results without +creating files. + +Analysis-table contract +----------------------- + +Scientific columns are defined by +``PQAnalysis/analysis/_output_schemas.py``. Each +:class:`~PQAnalysis.analysis.output.AnalysisSchema` records stable ASCII field +identifiers, display symbols, units and an optional xmgrace projection. + +Writers convert numerical results into an +:class:`~PQAnalysis.analysis.output.AnalysisTable`. Native formatting may retain +legacy row layout, while CSV, TSV and XVG use the same schema. Construct all +requested writers before the calculation starts so an existing output path +fails before expensive work or partial output occurs. diff --git a/docs/source/developerGuide/developerGuide.rst b/docs/source/developerGuide/developerGuide.rst index 13f1d547..0dee40ba 100644 --- a/docs/source/developerGuide/developerGuide.rst +++ b/docs/source/developerGuide/developerGuide.rst @@ -3,15 +3,50 @@ Development =========== -PQAnalysis uses a ``dev`` integration branch and releases from ``main``. -Feature and fix pull requests normally target ``dev``; release pull requests -merge ``dev`` into ``main``. - -Local setup ------------ - -Clone the repository and install editable development, test and documentation -dependencies: +PQAnalysis uses a ``dev`` integration branch and releases from ``main``. This +section documents the code boundaries and evidence required to extend the +package, not only the mechanics of opening a pull request. + +Extension path +-------------- + +.. list-table:: Analysis implementation path + :class: pq-record-table pq-extension-table + :header-rows: 1 + :widths: 24 38 38 + + * - Stage + - Primary location + - Contract + * - Scientific method + - ``PQAnalysis/analysis//`` + - Estimator, normalization, units and result shape + * - Python interface + - ``PQAnalysis/analysis//api.py`` + - Validated orchestration shared with the CLI + * - Command line + - ``PQAnalysis/cli/.py`` + - Arguments and dispatch, without duplicate computation + * - Scientific output + - ``PQAnalysis/analysis/_output_schemas.py`` + - Stable fields, symbols, units and plot projection + * - Evidence + - ``tests/analysis//`` and ``tests/data//`` + - Analytical, independent, parity and end-to-end tests + +.. toctree:: + :maxdepth: 1 + + architecture + adding-analysis + validation + release + +Local environment +----------------- + +Install the package with development, test and documentation dependencies in an +isolated environment: .. code-block:: console @@ -21,90 +56,69 @@ dependencies: $ source .venv/bin/activate $ python -m pip install -e ".[dev,test,docs]" -Keep changes focused and add tests at the same ownership boundary as the -behavior being changed. - -Tests ------ +Quality gates +------------- -The full test script runs the suite with runtime type checking enabled and -again with release settings: +``pytest.sh`` runs the suite with debug runtime type checking and repeats it +with release settings: .. code-block:: console $ bash pytest.sh + $ bash pytest.sh tests/analysis/rdf -q -For a focused iteration, pass ordinary pytest arguments: +Run pylint against the package and retain a score above the CI threshold of +9.75: .. code-block:: console - $ bash pytest.sh tests/analysis/rdf -q - -Documentation -------------- + $ python -m pylint PQAnalysis --persistent n -Build the complete documentation with warnings treated as errors: +Public Python interfaces use NumPy-style docstrings. Document parameters, +returns, raised exceptions, units and array shapes. Inspect coverage with: .. code-block:: console - $ python -m sphinx -W --keep-going \ - -b html docs/source docs/build/html + $ docstr-coverage PQAnalysis -Check internal and external links separately: +Documentation +------------- + +Build the complete documentation and check links with warnings treated as +errors: .. code-block:: console - $ python -m sphinx -W --keep-going \ + $ python -m sphinx -E -W --keep-going \ + -b html docs/source docs/build/html + $ python -m sphinx -E -W --keep-going \ -b linkcheck docs/source docs/build/linkcheck The API reference is generated from package modules when Sphinx starts. Do not -hand-edit generated files under ``docs/source/code`` unless the generator or -its templates are being changed. User-facing scientific conventions belong in -the maintained analysis, data and reference pages. - -Documentation structure ------------------------ - -* ``getting-started.rst`` provides the shortest working path. -* ``analyses/`` explains physical definitions, inputs and interpretation. -* ``_plots/`` contains executable Matplotlib figures built from documented - analytic models or versioned validation fixtures. -* ``data/`` covers file grammar, trajectories, selections and conversion. -* ``reference/`` indexes CLI and Python interfaces. -* ``userGuide/analysisOutputFiles.rst`` is the canonical output-schema source. -* ``code/`` is generated API material. - -Every analysis guide should state the physical quantity, assumptions, units, -minimal input, output fields and interpretation limits. Keep duplicated option -tables in generated API documentation rather than copying them into several -manual pages. Figure captions must identify their data source and distinguish -analytic schematics, validation fixtures and physical benchmark results. +hand-edit generated files under ``docs/source/code``. Add public callables to +:doc:`../reference/functions`, and put implementation-level guidance in this +development section. + +Executable figures under ``docs/source/_plots`` must be deterministic. Captions +must distinguish analytic schematics, versioned validation fixtures and +physical benchmark results. Pull requests ------------- -Pull requests should be reviewer-readable and use a Conventional Commits title, -for example ``feat: add a new analysis command`` or -``fix(io): handle missing trajectory data``. The repository validates the PR -title and uses it as the squash-merge commit message. +Feature and fix pull requests normally target ``dev``. Release pull requests +merge ``dev`` into ``main``. Use a Conventional Commits PR title, such as +``feat: add a new analysis command`` or +``fix(io): handle missing trajectory data``; the title becomes the squash-merge +commit message. -The optional local commit-message hook provides earlier feedback: +Enable the optional local commit-message hook with: .. code-block:: console $ git config core.hooksPath .githooks -Before requesting review, run the focused tests for the change and every -relevant strict documentation build. CI publishes documentation only from -``main``; pull requests and ``dev`` pushes build it without deploying. - -Docstrings ----------- - -Public Python interfaces use NumPy-style docstrings. Document parameters, -returns, raised exceptions, units and array shapes precisely. Documentation -coverage can be inspected with: - -.. code-block:: console - - $ docstr-coverage PQAnalysis +Before requesting review, run the focused tests for the modified ownership +boundary and every relevant strict documentation build. Pull requests and +``dev`` pushes build documentation without deploying it; deployment occurs +from ``main``. diff --git a/docs/source/developerGuide/release.rst b/docs/source/developerGuide/release.rst new file mode 100644 index 00000000..5000f641 --- /dev/null +++ b/docs/source/developerGuide/release.rst @@ -0,0 +1,72 @@ +Release Process +=============== + +PQAnalysis uses ``dev`` as the integration branch and releases from ``main``. +Version strings are derived from Git tags by ``setuptools_scm``; do not edit the +generated ``PQAnalysis/_version.py`` file. + +Release boundary +---------------- + +The release workflow matches every pushed tag. A tag push can publish to PyPI +and TestPyPI, create a GitHub release, sign release artifacts and update +``CHANGELOG.md`` on ``main``. + +.. warning:: + + Treat ``git push origin vX.Y.Z`` as the publication action. Deleting a Git + tag does not remove an uploaded Python distribution. + +Pre-release checks +------------------ + +1. Open a release pull request from ``dev`` to ``main``. +2. Confirm that the release PR contains only reviewed integration changes. +3. Run both runtime-type-checking configurations with ``bash pytest.sh``. +4. Build the HTML documentation and link check with warnings as errors. +5. Confirm the Conventional Commits history produces meaningful release notes. +6. Verify the intended version is greater than every existing release tag. + +The local verification commands are: + +.. code-block:: console + + $ git fetch origin --tags + $ bash pytest.sh + $ python -m sphinx -E -W --keep-going \ + -b html docs/source docs/build/html + $ python -m sphinx -E -W --keep-going \ + -b linkcheck docs/source docs/build/linkcheck + +Tagging +------- + +After the release PR is merged and the ``main`` checks pass, tag the verified +``main`` commit with the existing ``vMAJOR.MINOR.PATCH`` convention: + +.. code-block:: console + + $ git switch main + $ git pull --ff-only origin main + $ git tag -a vX.Y.Z -m "PQAnalysis vX.Y.Z" + $ git push origin vX.Y.Z + +Use a major version for incompatible public API or file-contract changes, a +minor version for backward-compatible functionality and a patch version for +backward-compatible fixes. + +Publication verification +------------------------ + +Do not consider the release complete until all of these are confirmed: + +* the release workflow succeeded; +* the new version is available from PyPI; +* the GitHub release contains the signed distribution artifacts; +* ``CHANGELOG.md`` was updated on ``main``; +* the documentation workflow deployed the verified ``main`` build; +* a clean environment can install the published version and run + ``pqanalysis --version``. + +Published PyPI files are immutable. Correct a defective release with a new +patch release rather than moving or reusing its tag. diff --git a/docs/source/developerGuide/validation.rst b/docs/source/developerGuide/validation.rst new file mode 100644 index 00000000..fe775568 --- /dev/null +++ b/docs/source/developerGuide/validation.rst @@ -0,0 +1,91 @@ +Scientific Validation +===================== + +Tests should identify what kind of evidence they provide. Agreement with a +previous implementation establishes compatibility; it does not by itself +establish physical correctness. + +Evidence classes +---------------- + +.. list-table:: Validation evidence + :class: pq-record-table pq-validation-table + :header-rows: 1 + :widths: 25 35 40 + + * - Evidence + - Purpose + - Suitable reference + * - Analytical invariant + - Verify definitions and limiting cases + - Hand-derived value, conservation law or exactly soluble system + * - Independent implementation + - Detect shared implementation errors + - ASE, a direct NumPy expression or another documented program + * - Legacy parity + - Preserve established PQ tool behavior + - Output generated by the named legacy executable and input + * - Kernel parity + - Keep optimized and fallback paths equivalent + - Direct comparison on identical arrays and parameters + * - End-to-end behavior + - Verify parsing, orchestration and serialization + - CLI/API run with versioned fixtures and expected output + +Use more than one evidence class for a new scientific method. A reference file +produced by the implementation under test is not independent validation. + +Reference-data provenance +------------------------- + +Store compact, deterministic fixtures under ``tests/data//``. The test +module or a README beside the data must record: + +* the program and version that generated the reference; +* the complete source input and relevant options; +* the physical units and column meanings; +* any precision loss caused by text serialization; +* the reason for the selected numerical tolerance. + +Do not replace a reference file merely to make a failing test pass. A reference +change must be reviewable as either a corrected scientific definition, an +intentional compatibility change or a newly generated independent benchmark. + +Numerical tolerances +-------------------- + +Prefer exact equality for integer counts, field names and deterministic text. +For floating-point data, choose ``rtol`` and ``atol`` from the numerical method, +reference precision and expected magnitude. Record relaxed tolerances next to +the assertion. Do not use one package-wide tolerance for observables with +different scales. + +Fast kernels may accumulate values in a different order from NumPy fallbacks. +Their parity tolerance should cover the expected floating-point summation +difference, not unrelated algorithmic changes. + +Test commands +------------- + +``pytest.sh`` runs the requested tests once with debug runtime type checking and +once with release settings: + +.. code-block:: console + + $ bash pytest.sh tests/analysis/rdf -q + $ bash pytest.sh tests/analysis/msd -q + $ bash pytest.sh tests/analysis/vacf -q + +Run the complete suite before review: + +.. code-block:: console + + $ bash pytest.sh + +Documentation figures +--------------------- + +Executable figures under ``docs/source/_plots`` may use an analytic model or a +versioned validation fixture. Their captions must state which one. A schematic +must not be presented as simulation output, and a legacy parity fixture must not +be described as an independent physical benchmark. diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index be5ba7aa..955bd345 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -72,7 +72,9 @@ Next steps ---------- * :doc:`analyses/index` compares the physical observables and required data. -* :doc:`data/index` defines input grammar, trajectory conventions and table - formats. +* :doc:`reference/functions` lists public Python workflows and numerical + functions. * :doc:`reference/cli` lists commands and options. * :doc:`reference/api` identifies the Python analysis and I/O entry points. +* :doc:`developerGuide/developerGuide` documents architecture, extension and + validation. diff --git a/docs/source/index.rst b/docs/source/index.rst index f34610a5..9f8c4da0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,7 +7,7 @@ velocities and Hessians, then produces documented scientific tables for structural, transport and vibrational observables. :doc:`Get started ` | :doc:`Choose an analysis ` | -:doc:`Work with data ` | :doc:`Command reference ` +:doc:`Python functions ` | :doc:`Develop PQAnalysis ` Quick start ----------- @@ -30,6 +30,7 @@ Analysis methods ---------------- .. list-table:: Implemented observables + :class: pq-record-table pq-method-table :header-rows: 1 :widths: 24 38 38 @@ -52,31 +53,47 @@ Analysis methods - Velocities and atomic masses - Frame-resolved total linear momentum -Scientific output ------------------ +Python interface +---------------- + +The public analysis functions use the same validated input readers and +scientific kernels as the command line: + +.. code-block:: python -Native analysis tables retain their established numeric layout and add a -compact UTF-8 metadata header. Stable ASCII field names support scripts while -Unicode symbols and units describe the physical quantities. + from PQAnalysis.analysis import rdf, read_analysis_table -.. code-block:: text + rdf("rdf.in", export_files=["rdf.csv"]) + table = read_analysis_table("rdf.csv") - # PQAnalysis: Radial distribution function - # FIELDS r_i g_r_i N_r_i g_r_i_dV_i H_i_minus_E_i - # SYMBOLS rᵢ g(rᵢ) N(rᵢ) g(rᵢ)ΔVᵢ Hᵢ−Eᵢ - # UNITS Å 1 1 ų pairs - 0.5 0.0 0.0 0.0 -0.05026548245743666 +The :doc:`function index ` exposes analysis workflows, +numerical methods, scientific-table operations and simulation-file I/O without +requiring navigation through the generated module tree. + +Development +----------- -See :ref:`analysisOutputFiles` for column definitions, normalization -conventions and conversion behavior. +New methods follow a documented path from estimator and validation evidence to +the public API, CLI and schema-backed output. See +:doc:`Adding an Analysis ` for the complete +implementation checklist and :doc:`Architecture ` +for package ownership boundaries. .. toctree:: :hidden: :maxdepth: 2 - :caption: Documentation + :caption: Use PQAnalysis getting-started analyses/index - data/index - reference/index - Development + Python Functions + Command Line + Files and Formats + Package Reference + +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: Develop PQAnalysis + + developerGuide/developerGuide diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index 63665570..fd5c00ce 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -1,30 +1,38 @@ -Python API -========== +Package Reference +================= -The public analysis wrappers accept the same input files as the command line -and are the simplest integration points: +Start with the :doc:`functions` page for callable analysis, numerical and I/O +interfaces. This page maps the principal data types and generated module +reference. -.. list-table:: Analysis entry points +Core types +---------- + +.. list-table:: Principal data types + :class: pq-record-table pq-types-table :header-rows: 1 :widths: 34 66 - * - Function - - Purpose - * - :func:`PQAnalysis.analysis.rdf.api.rdf` - - Radial distribution analysis - * - :func:`PQAnalysis.analysis.msd.api.msd` - - Mean square displacement analysis - * - :func:`PQAnalysis.analysis.vacf.api.vacf` - - Velocity or charge-flux correlation analysis - * - :func:`PQAnalysis.analysis.vibrational.api.vibrations` - - Vibrational analysis from a structure and Hessian - * - :func:`PQAnalysis.analysis.momentum.api.check_momentum` - - Frame-resolved total linear momentum + * - Type + - Role + * - :class:`PQAnalysis.atomic_system.AtomicSystem` + - One structure with coordinates, cell and topology + * - :class:`PQAnalysis.traj.Trajectory` + - Ordered atomic-system frames + * - :class:`PQAnalysis.topology.Topology` + - Atoms, residues, molecular identity and bonded topology + * - :class:`PQAnalysis.topology.Selection` + - Atom selection parser and index resolution + * - :class:`PQAnalysis.analysis.output.AnalysisTable` + - Numerical analysis data coupled to scientific column metadata + * - :class:`PQAnalysis.analysis.output.AnalysisSchema` + - Stable fields, symbols, units and plot defaults Package areas ------------- .. list-table:: Generated package reference + :class: pq-record-table pq-package-reference-table :header-rows: 1 :widths: 34 66 @@ -43,5 +51,5 @@ Package areas * - :doc:`Package index <../code/PQAnalysis>` - Generated module hierarchy -Use the analysis guides for physical conventions and the generated reference -for signatures and implementation details. +Use the analysis guides for physical conventions, the function index for +callable workflows and the generated reference for implementation details. diff --git a/docs/source/reference/functions.rst b/docs/source/reference/functions.rst new file mode 100644 index 00000000..73645e48 --- /dev/null +++ b/docs/source/reference/functions.rst @@ -0,0 +1,84 @@ +.. _function-index: + +Function Index +============== + +This page lists the callable Python interfaces intended for direct use. The +analysis wrappers accept the same input files as their command-line +counterparts. Lower-level numerical functions operate on arrays or PQAnalysis +objects and do not parse command-line arguments. + +Analysis workflows +------------------ + +.. autosummary:: + + ~PQAnalysis.analysis.rdf.api.rdf + ~PQAnalysis.analysis.msd.api.msd + ~PQAnalysis.analysis.vacf.api.vacf + ~PQAnalysis.analysis.vibrational.api.vibrations + ~PQAnalysis.analysis.momentum.api.check_momentum + ~PQAnalysis.analysis.spectrum_broadening.api.build_spectrum + +Numerical methods +----------------- + +.. autosummary:: + + ~PQAnalysis.analysis.vacf.spectrum.apodization_window + ~PQAnalysis.analysis.vacf.spectrum.vacf_spectrum + ~PQAnalysis.analysis.spectrum_broadening.spectrum_broadening.alpha_from_fwhm + ~PQAnalysis.analysis.spectrum_broadening.spectrum_broadening.fwhm_from_alpha + ~PQAnalysis.analysis.spectrum_broadening.spectrum_broadening.wavenumber_grid + ~PQAnalysis.analysis.spectrum_broadening.spectrum_broadening.broaden + ~PQAnalysis.analysis.vibrational.vibrational_analysis.calculate + ~PQAnalysis.analysis.vibrational.vibrational_analysis.read_hessian_file + ~PQAnalysis.analysis.vibrational.vibrational_analysis.select_mode_indices + +Analysis tables +--------------- + +.. autosummary:: + + ~PQAnalysis.analysis.output.infer_output_format + ~PQAnalysis.analysis.output.read_analysis_table + ~PQAnalysis.analysis.output.write_analysis_table + ~PQAnalysis.analysis.output.convert_analysis_output + +Structure and trajectory I/O +---------------------------- + +.. autosummary:: + + ~PQAnalysis.io.traj_file.api.read_trajectory + ~PQAnalysis.io.traj_file.api.read_trajectory_generator + ~PQAnalysis.io.traj_file.api.write_trajectory + ~PQAnalysis.io.traj_file.api.calculate_frames_of_trajectory_file + ~PQAnalysis.io.restart_file.api.read_restart_file + ~PQAnalysis.io.restart_file.api.write_restart_file + ~PQAnalysis.io.gen_file.api.read_gen_file + ~PQAnalysis.io.gen_file.api.write_gen_file + ~PQAnalysis.io.topology_file.api.read_topology_file + ~PQAnalysis.io.topology_file.api.write_topology_file + ~PQAnalysis.io.box_reader.read_box + ~PQAnalysis.io.optimizer_file_reader.read_optimizer_file + ~PQAnalysis.io.write_api.write + ~PQAnalysis.io.write_api.write_box + ~PQAnalysis.traj.api.check_trajectory_pbc + ~PQAnalysis.traj.api.check_trajectory_vacuum + +Format conversion +----------------- + +.. autosummary:: + + ~PQAnalysis.io.conversion_api.rst2xyz + ~PQAnalysis.io.conversion_api.xyz2rst + ~PQAnalysis.io.conversion_api.xyz2gen + ~PQAnalysis.io.conversion_api.gen2xyz + ~PQAnalysis.io.conversion_api.traj2box + ~PQAnalysis.io.conversion_api.traj2extxyz + ~PQAnalysis.io.conversion_api.traj2qmcfc + +See :doc:`api` for classes, enums, exceptions and the generated module +hierarchy. diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 8c7373ed..3507129c 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -1,3 +1,5 @@ +:orphan: + Reference ========= @@ -5,14 +7,8 @@ Use the command reference for shell workflows and the Python API reference for library integration. Scientific output definitions remain centralized so CLI and API users share the same field names, units and normalization conventions. +* :doc:`functions` lists public Python functions by task. * :doc:`cli` covers analysis, conversion and simulation-support commands. -* :doc:`api` lists public analysis functions and generated package modules. +* :doc:`api` maps core classes and generated package modules. * :ref:`analysisOutputFiles` specifies table fields, symbols, units and serialization formats. - -.. toctree:: - :hidden: - :maxdepth: 1 - - cli - api diff --git a/docs/source/userGuide/userGuide.rst b/docs/source/userGuide/userGuide.rst index de7e2886..d826ab05 100644 --- a/docs/source/userGuide/userGuide.rst +++ b/docs/source/userGuide/userGuide.rst @@ -9,5 +9,7 @@ This compatibility page points to the current task-oriented documentation: * :doc:`../getting-started`: installation, first RDF calculation and outputs * :doc:`../analyses/index`: estimators, assumptions and interpretation +* :doc:`../reference/functions`: public Python functions by task +* :doc:`../reference/cli`: command-line interfaces * :doc:`../data/index`: input grammar, trajectories and scientific tables -* :doc:`../reference/index`: command-line and Python interfaces +* :doc:`../developerGuide/developerGuide`: architecture and contribution work From d0da85c05d2256af6c767dde25913d1a6b691702 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 13:59:04 +0200 Subject: [PATCH 04/12] docs: refine VACF notation and figure --- docs/source/_plots/vacf.py | 26 ++++++++++++++----- docs/source/analyses/index.rst | 2 +- docs/source/analyses/vacf.rst | 5 +++- docs/source/userGuide/analysisOutputFiles.rst | 2 +- 4 files changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/source/_plots/vacf.py b/docs/source/_plots/vacf.py index 80598b2e..8bbd64f8 100644 --- a/docs/source/_plots/vacf.py +++ b/docs/source/_plots/vacf.py @@ -6,7 +6,7 @@ from _style import COLORS, PROJECT_ROOT, apply_style -apply_style((7.2, 5.1)) +apply_style((6.2, 5.5)) correlation = np.loadtxt(PROJECT_ROOT / "tests/data/vacf/vacf_ref.dat") spectrum = np.loadtxt( @@ -31,8 +31,15 @@ linestyle=":", linewidth=1.0, ) -correlation_axis.set_xlabel(r"Lag time $t$ / ps") -correlation_axis.set_ylabel(r"$C_v(t)$") +correlation_axis.set_title( + "(a) Normalized velocity autocorrelation", + loc="left", + fontsize=9.5, + fontweight="semibold", + pad=8, +) +correlation_axis.set_xlabel("Lag time, t / ps") +correlation_axis.set_ylabel("Cᵥᵥ(t)") correlation_axis.set_xlim(correlation[0, 0], correlation[-1, 0]) correlation_axis.set_ylim(-1.05, 1.05) @@ -41,10 +48,17 @@ spectrum[:, 1], color=COLORS["orange"], ) -spectrum_axis.set_xlabel(r"Wavenumber $\tilde{\nu}$ / $\mathrm{cm}^{-1}$") -spectrum_axis.set_ylabel("Amplitude / a.u.") +spectrum_axis.set_title( + "(b) Hann-window cosine-transform spectrum", + loc="left", + fontsize=9.5, + fontweight="semibold", + pad=8, +) +spectrum_axis.set_xlabel("Wavenumber, ν̃ / cm⁻¹") +spectrum_axis.set_ylabel("|Ĉ(ν̃)| / a.u.") spectrum_axis.set_xlim(0.0, 4000.0) spectrum_axis.set_ylim(bottom=0.0) -figure.tight_layout() +figure.tight_layout(h_pad=1.4) plt.show() diff --git a/docs/source/analyses/index.rst b/docs/source/analyses/index.rst index 481e54e8..6985cfde 100644 --- a/docs/source/analyses/index.rst +++ b/docs/source/analyses/index.rst @@ -25,7 +25,7 @@ Choose by input data - :math:`\langle |\mathbf{r}(t)-\mathbf{r}(0)|^2\rangle` * - VACF - Velocities and frame time step - - Normalized :math:`C_v(t)` and its spectrum + - Normalized :math:`C_{vv}(t)` and its spectrum * - Vibrations - Structure, masses and Cartesian Hessian - Normal-mode wavenumbers and force constants diff --git a/docs/source/analyses/vacf.rst b/docs/source/analyses/vacf.rst index 42bcb270..b3662500 100644 --- a/docs/source/analyses/vacf.rst +++ b/docs/source/analyses/vacf.rst @@ -6,10 +6,13 @@ velocities lose memory of their initial direction: .. math:: - C_v(t) = + C_{vv}(t) = \frac{\left\langle \sum_i \mathbf{v}_i(0)\cdot\mathbf{v}_i(t)\right\rangle} {\left\langle \sum_i \mathbf{v}_i(0)\cdot\mathbf{v}_i(0)\right\rangle}. +The brackets denote an average over admissible time origins, and the sum runs +over the selected atoms. This normalization gives :math:`C_{vv}(0)=1`. + PQAnalysis can transform the correlation to a wavenumber-domain spectrum. If static or time-dependent partial charges are supplied, it correlates :math:`q_i\mathbf{v}_i` instead, producing a charge-flux spectrum that diff --git a/docs/source/userGuide/analysisOutputFiles.rst b/docs/source/userGuide/analysisOutputFiles.rst index 4112a05e..74ff4a8d 100644 --- a/docs/source/userGuide/analysisOutputFiles.rst +++ b/docs/source/userGuide/analysisOutputFiles.rst @@ -294,7 +294,7 @@ normalized by their zero-lag value, including charge-weighted correlations. * - 1 - Wavenumber - Legacy cosine-transform frequency axis - - cm\ :sup:`-1` + - cm⁻¹ * - 2 - Spectrum amplitude - Absolute cosine-transform amplitude of the optionally windowed From dae0584488a0c998a8a4c5bc9534c6c2ec2c0c9f Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:41:02 +0200 Subject: [PATCH 05/12] docs: fix compact layout and prose --- README.md | 11 ++++++++--- docs/source/_plots/vacf.py | 4 ++-- docs/source/_static/css/custom.css | 6 ++++++ docs/source/data/index.rst | 2 +- docs/source/developerGuide/developerGuide.rst | 6 +++--- docs/source/index.rst | 12 ++++++------ docs/source/reference/api.rst | 4 ++-- docs/source/reference/functions.rst | 8 ++++---- docs/source/userGuide/userGuide.rst | 3 ++- 9 files changed, 34 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 20965f3b..ea014b9a 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,14 @@ [![codecov](https://codecov.io/gh/MolarVerse/PQAnalysis/graph/badge.svg?token=IDFK8L6IIQ)](https://codecov.io/gh/MolarVerse/PQAnalysis) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -The main purpose of this package is to provide useful tools for the analysis of the Molecular Dynamics software package [PQ](https://github.com/MolarVerse/PQ). Furthermore, the intent of this package is to enable straightforward implementations of newly developed analysis tools on top of the provided API. - -The future development of this package focuses on two main goals. On the one hand the enhancement of the provided analysis tools and extending its API to be compatible with many other different Molecular Dynamics engines. As this project is only a *hobby* project of the maintainers, any contributions considering enhancement or bug fixes are highly welcomed. +PQAnalysis reads structures, trajectories, velocities and Hessians produced by +[PQ](https://github.com/MolarVerse/PQ). Its command-line and Python interfaces +share parsers, numerical kernels and schema-defined outputs for RDF, MSD, VACF, +vibrational, spectral and momentum analyses. + +Development focuses on validated analysis methods and support for additional +molecular-dynamics engines. The maintainers develop PQAnalysis in their free +time; focused analysis contributions and bug fixes are welcome. ## Installation diff --git a/docs/source/_plots/vacf.py b/docs/source/_plots/vacf.py index 8bbd64f8..4bb86c76 100644 --- a/docs/source/_plots/vacf.py +++ b/docs/source/_plots/vacf.py @@ -35,7 +35,7 @@ "(a) Normalized velocity autocorrelation", loc="left", fontsize=9.5, - fontweight="semibold", + fontweight="bold", pad=8, ) correlation_axis.set_xlabel("Lag time, t / ps") @@ -52,7 +52,7 @@ "(b) Hann-window cosine-transform spectrum", loc="left", fontsize=9.5, - fontweight="semibold", + fontweight="bold", pad=8, ) spectrum_axis.set_xlabel("Wavenumber, ν̃ / cm⁻¹") diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index 1f65228e..0424044f 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -56,6 +56,12 @@ img.plot-directive + figcaption { overflow-x: auto; } +@media (max-width: 44rem), (max-height: 32rem) { + .back-to-top { + display: none; + } +} + @media (max-width: 44rem) { article table.autosummary, article table.pq-record-table { diff --git a/docs/source/data/index.rst b/docs/source/data/index.rst index f6a2c24b..9b5535e5 100644 --- a/docs/source/data/index.rst +++ b/docs/source/data/index.rst @@ -5,7 +5,7 @@ PQAnalysis separates simulation data, analysis configuration and output-table serialization. File extensions select output formats, while input content and explicit engine options determine how trajectories are read. -This section covers four interfaces: +Four file contracts govern analysis workflows: * :ref:`inputFile` defines the key-value grammar. * :ref:`analysisOutputFiles` defines table fields, symbols and units. diff --git a/docs/source/developerGuide/developerGuide.rst b/docs/source/developerGuide/developerGuide.rst index 0dee40ba..2e96bb0a 100644 --- a/docs/source/developerGuide/developerGuide.rst +++ b/docs/source/developerGuide/developerGuide.rst @@ -3,9 +3,9 @@ Development =========== -PQAnalysis uses a ``dev`` integration branch and releases from ``main``. This -section documents the code boundaries and evidence required to extend the -package, not only the mechanics of opening a pull request. +PQAnalysis integrates changes on ``dev`` and releases from ``main``. The guides +define package boundaries, implementation contracts, validation evidence and +release operations. Extension path -------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 9f8c4da0..24885938 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -66,18 +66,18 @@ scientific kernels as the command line: rdf("rdf.in", export_files=["rdf.csv"]) table = read_analysis_table("rdf.csv") -The :doc:`function index ` exposes analysis workflows, -numerical methods, scientific-table operations and simulation-file I/O without -requiring navigation through the generated module tree. +The :doc:`function index ` groups analysis workflows, +numerical methods, scientific-table operations and simulation-file I/O by +task. Development ----------- New methods follow a documented path from estimator and validation evidence to the public API, CLI and schema-backed output. See -:doc:`Adding an Analysis ` for the complete -implementation checklist and :doc:`Architecture ` -for package ownership boundaries. +:doc:`Adding an Analysis ` for the required +implementation steps and :doc:`Architecture ` for +package ownership boundaries. .. toctree:: :hidden: diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index fd5c00ce..d5f81ec9 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -1,8 +1,8 @@ Package Reference ================= -Start with the :doc:`functions` page for callable analysis, numerical and I/O -interfaces. This page maps the principal data types and generated module +The :doc:`functions` page documents callable analysis, numerical and I/O +interfaces. The tables below map principal data types to the generated module reference. Core types diff --git a/docs/source/reference/functions.rst b/docs/source/reference/functions.rst index 73645e48..00d6e8da 100644 --- a/docs/source/reference/functions.rst +++ b/docs/source/reference/functions.rst @@ -3,10 +3,10 @@ Function Index ============== -This page lists the callable Python interfaces intended for direct use. The -analysis wrappers accept the same input files as their command-line -counterparts. Lower-level numerical functions operate on arrays or PQAnalysis -objects and do not parse command-line arguments. +Callable Python interfaces are grouped below by task. Analysis wrappers accept +the same input files as their command-line counterparts. Lower-level numerical +functions operate on arrays or PQAnalysis objects and do not parse command-line +arguments. Analysis workflows ------------------ diff --git a/docs/source/userGuide/userGuide.rst b/docs/source/userGuide/userGuide.rst index d826ab05..bfec87c7 100644 --- a/docs/source/userGuide/userGuide.rst +++ b/docs/source/userGuide/userGuide.rst @@ -5,7 +5,8 @@ User Guide ========== -This compatibility page points to the current task-oriented documentation: +The former user-guide URL is retained for compatibility. Current documentation +is organized by task: * :doc:`../getting-started`: installation, first RDF calculation and outputs * :doc:`../analyses/index`: estimators, assumptions and interpretation From 40ba2b90087c9ceb6728f2cd3533e2b769fd9655 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 15:05:48 +0200 Subject: [PATCH 06/12] docs: use representative VACF model --- docs/source/_plots/vacf.py | 48 +++++++++++++++++++++++------------ docs/source/analyses/vacf.rst | 10 +++++--- 2 files changed, 38 insertions(+), 20 deletions(-) diff --git a/docs/source/_plots/vacf.py b/docs/source/_plots/vacf.py index 4bb86c76..52c11b83 100644 --- a/docs/source/_plots/vacf.py +++ b/docs/source/_plots/vacf.py @@ -1,18 +1,34 @@ -"""VACF and Hann-window spectrum from the validation fixture.""" +"""Analytical damped VACF and its PQAnalysis spectrum.""" import matplotlib.pyplot as plt import numpy as np -from _style import COLORS, PROJECT_ROOT, apply_style +from PQAnalysis.analysis.vacf.spectrum import vacf_spectrum + +from _style import COLORS, apply_style apply_style((6.2, 5.5)) -correlation = np.loadtxt(PROJECT_ROOT / "tests/data/vacf/vacf_ref.dat") -spectrum = np.loadtxt( - PROJECT_ROOT / "tests/data/vacf/spectrum_hann_ref.dat" +time = np.arange(0.0, 0.3005, 0.0005) +correlation = ( + 0.85 * np.exp(-(time / 0.075) ** 2) + * np.cos(2.0 * np.pi * 9.0 * time) + + 0.15 * np.exp(-(time / 0.035) ** 2) + * np.cos(2.0 * np.pi * 42.0 * time) +) + +wavenumbers, amplitudes, _ = vacf_spectrum( + time, + correlation, + ftsize=4096, + window_function="hann", + window_stop=float(time[-1]), ) -spectrum = spectrum[spectrum[:, 0] <= 4000.0] +display_range = wavenumbers <= 4000.0 +wavenumbers = wavenumbers[display_range] +amplitudes = amplitudes[display_range] +amplitudes /= amplitudes.max() figure, (correlation_axis, spectrum_axis) = plt.subplots( 2, @@ -21,8 +37,8 @@ ) correlation_axis.plot( - correlation[:, 0], - correlation[:, 1], + time, + correlation, color=COLORS["blue"], ) correlation_axis.axhline( @@ -32,7 +48,7 @@ linewidth=1.0, ) correlation_axis.set_title( - "(a) Normalized velocity autocorrelation", + "(a) Normalized damped VACF", loc="left", fontsize=9.5, fontweight="bold", @@ -40,25 +56,25 @@ ) correlation_axis.set_xlabel("Lag time, t / ps") correlation_axis.set_ylabel("Cᵥᵥ(t)") -correlation_axis.set_xlim(correlation[0, 0], correlation[-1, 0]) -correlation_axis.set_ylim(-1.05, 1.05) +correlation_axis.set_xlim(time[0], time[-1]) +correlation_axis.set_ylim(-0.65, 1.05) spectrum_axis.plot( - spectrum[:, 0], - spectrum[:, 1], + wavenumbers, + amplitudes, color=COLORS["orange"], ) spectrum_axis.set_title( - "(b) Hann-window cosine-transform spectrum", + "(b) Hann-window spectrum", loc="left", fontsize=9.5, fontweight="bold", pad=8, ) spectrum_axis.set_xlabel("Wavenumber, ν̃ / cm⁻¹") -spectrum_axis.set_ylabel("|Ĉ(ν̃)| / a.u.") +spectrum_axis.set_ylabel("Relative amplitude") spectrum_axis.set_xlim(0.0, 4000.0) -spectrum_axis.set_ylim(bottom=0.0) +spectrum_axis.set_ylim(0.0, 1.05) figure.tight_layout(h_pad=1.4) plt.show() diff --git a/docs/source/analyses/vacf.rst b/docs/source/analyses/vacf.rst index b3662500..e39b34b5 100644 --- a/docs/source/analyses/vacf.rst +++ b/docs/source/analyses/vacf.rst @@ -22,10 +22,12 @@ Correlation and spectrum ------------------------ .. plot:: _plots/vacf.py - :alt: Velocity autocorrelation function and its Hann-window spectrum - :caption: Bundled VACF validation fixture and its Hann-window cosine - transform. Spectrum amplitudes are reported in arbitrary units; the - displayed range is limited to 4000 cm⁻¹. + :alt: Analytical normalized VACF with a negative correlation lobe and its + Hann-window spectrum + :caption: Analytical two-mode VACF and its PQAnalysis Hann-window cosine + transform. The 300 and 1400 cm⁻¹ modes use Gaussian decay times of + 0.075 and 0.035 ps, respectively. The correlation and spectrum are + normalized to unit maxima. Minimal input ------------- From 05ea674dea3cac55b67259678aabf374abdc0edb Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 7 Aug 2026 22:21:12 +0200 Subject: [PATCH 07/12] docs: clarify VACF apodization --- docs/source/_plots/vacf.py | 36 +++++++++++++++---------- docs/source/analyses/vacf.rst | 49 +++++++++++++++++++++++------------ 2 files changed, 56 insertions(+), 29 deletions(-) diff --git a/docs/source/_plots/vacf.py b/docs/source/_plots/vacf.py index 52c11b83..b60a9891 100644 --- a/docs/source/_plots/vacf.py +++ b/docs/source/_plots/vacf.py @@ -1,4 +1,4 @@ -"""Analytical damped VACF and its PQAnalysis spectrum.""" +"""Analytical two-band VACF and its PQAnalysis spectrum.""" import matplotlib.pyplot as plt import numpy as np @@ -10,22 +10,22 @@ apply_style((6.2, 5.5)) -time = np.arange(0.0, 0.3005, 0.0005) +time = np.arange(0.0, 0.5005, 0.0005) correlation = ( - 0.85 * np.exp(-(time / 0.075) ** 2) + 0.70 * np.exp(-(time / 0.22) ** 2) * np.cos(2.0 * np.pi * 9.0 * time) - + 0.15 * np.exp(-(time / 0.035) ** 2) - * np.cos(2.0 * np.pi * 42.0 * time) + + 0.30 * np.exp(-(time / 0.12) ** 2) + * np.cos(2.0 * np.pi * 18.0 * time) ) -wavenumbers, amplitudes, _ = vacf_spectrum( +wavenumbers, amplitudes, windowed_correlation = vacf_spectrum( time, correlation, - ftsize=4096, - window_function="hann", - window_stop=float(time[-1]), + ftsize=5000, + window_function="exponential", + window_param=4.0, ) -display_range = wavenumbers <= 4000.0 +display_range = wavenumbers <= 1000.0 wavenumbers = wavenumbers[display_range] amplitudes = amplitudes[display_range] amplitudes /= amplitudes.max() @@ -40,6 +40,15 @@ time, correlation, color=COLORS["blue"], + label="Unwindowed", +) +correlation_axis.plot( + time, + windowed_correlation, + color=COLORS["green"], + linestyle="--", + linewidth=1.6, + label="Exponential, 4 ps⁻¹", ) correlation_axis.axhline( 0.0, @@ -48,7 +57,7 @@ linewidth=1.0, ) correlation_axis.set_title( - "(a) Normalized damped VACF", + "(a) Normalized VACF", loc="left", fontsize=9.5, fontweight="bold", @@ -58,6 +67,7 @@ correlation_axis.set_ylabel("Cᵥᵥ(t)") correlation_axis.set_xlim(time[0], time[-1]) correlation_axis.set_ylim(-0.65, 1.05) +correlation_axis.legend(loc="upper right") spectrum_axis.plot( wavenumbers, @@ -65,7 +75,7 @@ color=COLORS["orange"], ) spectrum_axis.set_title( - "(b) Hann-window spectrum", + "(b) Exponential-window spectrum", loc="left", fontsize=9.5, fontweight="bold", @@ -73,7 +83,7 @@ ) spectrum_axis.set_xlabel("Wavenumber, ν̃ / cm⁻¹") spectrum_axis.set_ylabel("Relative amplitude") -spectrum_axis.set_xlim(0.0, 4000.0) +spectrum_axis.set_xlim(0.0, 1000.0) spectrum_axis.set_ylim(0.0, 1.05) figure.tight_layout(h_pad=1.4) diff --git a/docs/source/analyses/vacf.rst b/docs/source/analyses/vacf.rst index e39b34b5..8f8d5cd4 100644 --- a/docs/source/analyses/vacf.rst +++ b/docs/source/analyses/vacf.rst @@ -7,27 +7,36 @@ velocities lose memory of their initial direction: .. math:: C_{vv}(t) = - \frac{\left\langle \sum_i \mathbf{v}_i(0)\cdot\mathbf{v}_i(t)\right\rangle} - {\left\langle \sum_i \mathbf{v}_i(0)\cdot\mathbf{v}_i(0)\right\rangle}. + \left\langle + \frac{\sum_i \mathbf{v}_i(t_0)\cdot\mathbf{v}_i(t_0+t)} + {\sum_i \mathbf{v}_i(t_0)\cdot\mathbf{v}_i(t_0)} + \right\rangle_{t_0}. The brackets denote an average over admissible time origins, and the sum runs -over the selected atoms. This normalization gives :math:`C_{vv}(0)=1`. +over the selected atoms. This is the default, legacy-compatible estimator and +gives :math:`C_{vv}(0)=1`. The ``fft`` estimator instead averages the numerator +and denominator separately over all available origins before normalization. PQAnalysis can transform the correlation to a wavenumber-domain spectrum. If static or time-dependent partial charges are supplied, it correlates :math:`q_i\mathbf{v}_i` instead, producing a charge-flux spectrum that approximates an infrared spectrum. +The correlation written to ``out_file`` is not apodized. When a spectrum is +requested, ``window_function`` multiplies a copy of the correlation before the +cosine transform. The optional ``windowed_out_file`` records that copy. + Correlation and spectrum ------------------------ .. plot:: _plots/vacf.py - :alt: Analytical normalized VACF with a negative correlation lobe and its - Hann-window spectrum - :caption: Analytical two-mode VACF and its PQAnalysis Hann-window cosine - transform. The 300 and 1400 cm⁻¹ modes use Gaussian decay times of - 0.075 and 0.035 ps, respectively. The correlation and spectrum are - normalized to unit maxima. + :alt: Analytical normalized VACF, its exponentially windowed copy and the + resulting spectrum + :caption: Analytical normalized VACF for two Gaussian-broadened bands + centered at 300 and 600 cm⁻¹, with dephasing times of 0.22 and 0.12 ps. + The dashed curve applies an exponential window with a decay coefficient + of 4 ps⁻¹ before the PQAnalysis cosine transform. Spectrum amplitudes + are scaled to unit maximum. Minimal input ------------- @@ -49,18 +58,26 @@ Minimal input $ pqanalysis vacf vacf.in -The time step is specified in ps. ``window_function`` accepts -``exponential``, ``hann`` and ``blackman``. The default sliding-origin method -matches the legacy calculation; ``method = fft`` selects a denser-origin -Wiener-Khinchin estimator. +The time step is specified in ps. ``window`` is the maximum correlation lag in +frames; it is distinct from the apodization selected by ``window_function``. +The example multiplies only the spectrum input by +:math:`\exp[-(4\ \mathrm{ps}^{-1})t]`. ``window_function`` also accepts +``hann``, ``blackman`` and ``none``; ``none`` is the default. The default +sliding-origin method matches the legacy calculation. ``gap`` controls the +spacing between its time origins, not the lag-time spacing in ``out_file``; +``method = fft`` selects a denser-origin Wiener-Khinchin estimator. Interpretation -------------- * A rapidly decaying VACF indicates fast velocity decorrelation. -* Negative regions indicate backscattering or cage motion. -* The frequency spectrum depends on the sampling interval, correlation length, - apodization window and zero-padding size. +* In liquids, negative regions often indicate backscattering or cage motion; + in solids, sign oscillations reflect bound vibrational motion. +* The sampling interval sets the Nyquist limit, and the correlation length sets + the resolving power. Zero-padding provides a denser frequency grid but does + not add spectral resolution. +* Apodization reduces endpoint artifacts but changes band widths and + amplitudes; report the selected function and its parameters. * Charge-flux spectra require physically meaningful partial charges and should not be interpreted as absolute IR intensities without further calibration. From 81daf92c62a21cae00ad86266f58ed42a2db974c Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Thu, 20 Aug 2026 12:03:23 +0200 Subject: [PATCH 08/12] docs: fix deploy, sitemap and reference accuracy Address the review of the documentation draft: - add a configure-pages step with enablement so the first Pages deploy switches the repository source to GitHub Actions instead of failing against the legacy gh-pages setting - set sitemap_url_scheme to the plain link so the sitemap matches the flat deployed site instead of 404ing on language/version prefixes - correct the build_nep_traj description (Neuroevolution Potential training data, not nudged elastic band) - stop tracking the generated docs/source/code pages and ignore them together with docs/build, so local docs builds no longer dirty the working tree; drop the stale docs/autodoc.sh that conflicted with the better-apidoc build - clarify that only conversion/support tools accept --mode o; the input-file analyses have no overwrite flag - remove the orphaned reference/index.rst page and the unused breathe docs dependency; include momentum in the Cython-kernel list; ignore the generated momentum kernel source --- .github/workflows/docs.yml | 4 ++ .gitignore | 5 ++ docs/autodoc.sh | 1 - .../code/PQAnalysis.analysis.rdf.api.rst | 32 ---------- .../PQAnalysis.analysis.rdf.exceptions.rst | 33 ---------- .../code/PQAnalysis.analysis.rdf.rdf.rst | 32 ---------- ...sis.analysis.rdf.rdf_input_file_reader.rst | 32 ---------- ...is.analysis.rdf.rdf_output_file_writer.rst | 33 ---------- docs/source/code/PQAnalysis.analysis.rdf.rst | 27 -------- docs/source/code/PQAnalysis.analysis.rst | 24 ------- .../PQAnalysis.analysis.vibrational.api.rst | 32 ---------- ...alysis.analysis.vibrational.exceptions.rst | 32 ---------- .../code/PQAnalysis.analysis.vibrational.rst | 60 ------------------ ...lysis.vibrational.vibrational_analysis.rst | 63 ------------------- ...rational.vibrational_input_file_reader.rst | 32 ---------- ...PQAnalysis.atomic_system.atomic_system.rst | 32 ---------- .../PQAnalysis.atomic_system.exceptions.rst | 34 ---------- docs/source/code/PQAnalysis.atomic_system.rst | 24 ------- .../code/PQAnalysis.cli.add_molecules.rst | 32 ---------- .../code/PQAnalysis.cli.build_nep_traj.rst | 32 ---------- .../code/PQAnalysis.cli.continue_input.rst | 32 ---------- docs/source/code/PQAnalysis.cli.gen2xyz.rst | 32 ---------- docs/source/code/PQAnalysis.cli.rdf.rst | 32 ---------- docs/source/code/PQAnalysis.cli.rst | 31 --------- docs/source/code/PQAnalysis.cli.rst2xyz.rst | 32 ---------- docs/source/code/PQAnalysis.cli.traj2box.rst | 32 ---------- .../source/code/PQAnalysis.cli.traj2qmcfc.rst | 32 ---------- .../source/code/PQAnalysis.cli.vibrations.rst | 39 ------------ docs/source/code/PQAnalysis.cli.xyz2gen.rst | 32 ---------- docs/source/code/PQAnalysis.cli.xyz2rst.rst | 32 ---------- docs/source/code/PQAnalysis.config.rst | 25 -------- docs/source/code/PQAnalysis.core.api.rst | 32 ---------- .../source/code/PQAnalysis.core.atom.atom.rst | 32 ---------- .../code/PQAnalysis.core.atom.element.rst | 32 ---------- docs/source/code/PQAnalysis.core.atom.rst | 24 ------- .../source/code/PQAnalysis.core.cell.cell.rst | 32 ---------- docs/source/code/PQAnalysis.core.cell.rst | 23 ------- .../code/PQAnalysis.core.exceptions.rst | 34 ---------- docs/source/code/PQAnalysis.core.residue.rst | 33 ---------- docs/source/code/PQAnalysis.core.rst | 34 ---------- docs/source/code/PQAnalysis.exceptions.rst | 34 ---------- docs/source/code/PQAnalysis.formats.rst | 32 ---------- docs/source/code/PQAnalysis.io.api.rst | 32 ---------- docs/source/code/PQAnalysis.io.base.rst | 33 ---------- docs/source/code/PQAnalysis.io.box_writer.rst | 32 ---------- .../code/PQAnalysis.io.conversion_api.rst | 36 ----------- .../code/PQAnalysis.io.energy_file_reader.rst | 32 ---------- docs/source/code/PQAnalysis.io.exceptions.rst | 37 ----------- docs/source/code/PQAnalysis.io.formats.rst | 34 ---------- .../code/PQAnalysis.io.gen_file.api.rst | 33 ---------- .../PQAnalysis.io.gen_file.exceptions.rst | 32 ---------- ...PQAnalysis.io.gen_file.gen_file_reader.rst | 32 ---------- ...PQAnalysis.io.gen_file.gen_file_writer.rst | 32 ---------- docs/source/code/PQAnalysis.io.gen_file.rst | 26 -------- .../code/PQAnalysis.io.info_file_reader.rst | 32 ---------- ...alysis.io.input_file_reader.exceptions.rst | 34 ---------- ...QAnalysis.io.input_file_reader.formats.rst | 32 ---------- ...io.input_file_reader.input_file_parser.rst | 36 ----------- ...s.io.input_file_reader.pq.output_files.rst | 16 ----- ...ut_file_reader.pq.pq_input_file_reader.rst | 32 ---------- .../PQAnalysis.io.input_file_reader.pq.rst | 24 ------- ..._analysis.pqanalysis_input_file_reader.rst | 32 ---------- ...lysis.io.input_file_reader.pq_analysis.rst | 23 ------- .../code/PQAnalysis.io.input_file_reader.rst | 34 ---------- .../PQAnalysis.io.moldescriptor_reader.rst | 32 ---------- .../code/PQAnalysis.io.nep.nep_writer.rst | 32 ---------- docs/source/code/PQAnalysis.io.nep.rst | 23 ------- .../PQAnalysis.io.optimizer_file_reader.rst | 37 ----------- .../code/PQAnalysis.io.restart_file.api.rst | 32 ---------- .../PQAnalysis.io.restart_file.exceptions.rst | 32 ---------- ...nalysis.io.restart_file.restart_reader.rst | 32 ---------- ...nalysis.io.restart_file.restart_writer.rst | 32 ---------- .../code/PQAnalysis.io.restart_file.rst | 26 -------- docs/source/code/PQAnalysis.io.rst | 46 -------------- .../code/PQAnalysis.io.topology_file.api.rst | 33 ---------- ...PQAnalysis.io.topology_file.exceptions.rst | 32 ---------- .../code/PQAnalysis.io.topology_file.rst | 26 -------- ....io.topology_file.topology_file_reader.rst | 32 ---------- ....io.topology_file.topology_file_writer.rst | 48 -------------- .../code/PQAnalysis.io.traj_file.api.rst | 35 ----------- .../PQAnalysis.io.traj_file.exceptions.rst | 33 ---------- .../PQAnalysis.io.traj_file.frame_reader.rst | 32 ---------- ...Analysis.io.traj_file.raw_frame_reader.rst | 26 -------- docs/source/code/PQAnalysis.io.traj_file.rst | 27 -------- ...nalysis.io.traj_file.trajectory_reader.rst | 32 ---------- ...nalysis.io.traj_file.trajectory_writer.rst | 32 ---------- docs/source/code/PQAnalysis.io.virial.api.rst | 33 ---------- docs/source/code/PQAnalysis.io.virial.rst | 24 ------- .../PQAnalysis.io.virial.virial_reader.rst | 33 ---------- docs/source/code/PQAnalysis.io.write_api.rst | 33 ---------- .../code/PQAnalysis.physical_data.energy.rst | 32 ---------- .../PQAnalysis.physical_data.exceptions.rst | 32 ---------- docs/source/code/PQAnalysis.physical_data.rst | 24 ------- docs/source/code/PQAnalysis.rst | 52 --------------- .../code/PQAnalysis.tools.add_molecule.rst | 40 ------------ docs/source/code/PQAnalysis.tools.rst | 24 ------- .../PQAnalysis.tools.traj_to_com_traj.rst | 32 ---------- docs/source/code/PQAnalysis.topology.api.rst | 34 ---------- ...nalysis.topology.bonded_topology.angle.rst | 32 ---------- ...Analysis.topology.bonded_topology.bond.rst | 32 ---------- ...pology.bonded_topology.bonded_topology.rst | 32 ---------- ...ysis.topology.bonded_topology.dihedral.rst | 32 ---------- .../PQAnalysis.topology.bonded_topology.rst | 26 -------- .../code/PQAnalysis.topology.exceptions.rst | 32 ---------- docs/source/code/PQAnalysis.topology.rst | 35 ----------- .../code/PQAnalysis.topology.selection.rst | 34 ---------- .../PQAnalysis.topology.shake_topology.rst | 32 ---------- .../code/PQAnalysis.topology.topology.rst | 32 ---------- docs/source/code/PQAnalysis.traj.api.rst | 33 ---------- .../code/PQAnalysis.traj.exceptions.rst | 34 ---------- docs/source/code/PQAnalysis.traj.formats.rst | 33 ---------- docs/source/code/PQAnalysis.traj.rst | 26 -------- .../code/PQAnalysis.traj.trajectory.rst | 32 ---------- docs/source/code/PQAnalysis.type_checking.rst | 32 ---------- docs/source/code/PQAnalysis.types.rst | 25 -------- docs/source/code/PQAnalysis.utils.common.rst | 32 ---------- .../code/PQAnalysis.utils.custom_logging.rst | 48 -------------- .../code/PQAnalysis.utils.decorators.rst | 33 ---------- docs/source/code/PQAnalysis.utils.files.rst | 32 ---------- docs/source/code/PQAnalysis.utils.random.rst | 32 ---------- docs/source/code/PQAnalysis.utils.rst | 28 --------- docs/source/code/PQAnalysis.utils.units.rst | 25 -------- docs/source/conf.py | 4 ++ docs/source/developerGuide/architecture.rst | 2 +- docs/source/getting-started.rst | 6 +- docs/source/reference/cli.rst | 2 +- docs/source/reference/index.rst | 14 ----- pyproject.toml | 1 - 128 files changed, 19 insertions(+), 3854 deletions(-) delete mode 100755 docs/autodoc.sh delete mode 100644 docs/source/code/PQAnalysis.analysis.rdf.api.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.rdf.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.rdf.rdf.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.rdf.rdf_input_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.rdf.rdf_output_file_writer.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.rdf.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.vibrational.api.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.vibrational.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.vibrational.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.vibrational.vibrational_analysis.rst delete mode 100644 docs/source/code/PQAnalysis.analysis.vibrational.vibrational_input_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.atomic_system.atomic_system.rst delete mode 100644 docs/source/code/PQAnalysis.atomic_system.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.atomic_system.rst delete mode 100644 docs/source/code/PQAnalysis.cli.add_molecules.rst delete mode 100644 docs/source/code/PQAnalysis.cli.build_nep_traj.rst delete mode 100644 docs/source/code/PQAnalysis.cli.continue_input.rst delete mode 100644 docs/source/code/PQAnalysis.cli.gen2xyz.rst delete mode 100644 docs/source/code/PQAnalysis.cli.rdf.rst delete mode 100644 docs/source/code/PQAnalysis.cli.rst delete mode 100644 docs/source/code/PQAnalysis.cli.rst2xyz.rst delete mode 100644 docs/source/code/PQAnalysis.cli.traj2box.rst delete mode 100644 docs/source/code/PQAnalysis.cli.traj2qmcfc.rst delete mode 100644 docs/source/code/PQAnalysis.cli.vibrations.rst delete mode 100644 docs/source/code/PQAnalysis.cli.xyz2gen.rst delete mode 100644 docs/source/code/PQAnalysis.cli.xyz2rst.rst delete mode 100644 docs/source/code/PQAnalysis.config.rst delete mode 100644 docs/source/code/PQAnalysis.core.api.rst delete mode 100644 docs/source/code/PQAnalysis.core.atom.atom.rst delete mode 100644 docs/source/code/PQAnalysis.core.atom.element.rst delete mode 100644 docs/source/code/PQAnalysis.core.atom.rst delete mode 100644 docs/source/code/PQAnalysis.core.cell.cell.rst delete mode 100644 docs/source/code/PQAnalysis.core.cell.rst delete mode 100644 docs/source/code/PQAnalysis.core.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.core.residue.rst delete mode 100644 docs/source/code/PQAnalysis.core.rst delete mode 100644 docs/source/code/PQAnalysis.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.formats.rst delete mode 100644 docs/source/code/PQAnalysis.io.api.rst delete mode 100644 docs/source/code/PQAnalysis.io.base.rst delete mode 100644 docs/source/code/PQAnalysis.io.box_writer.rst delete mode 100644 docs/source/code/PQAnalysis.io.conversion_api.rst delete mode 100644 docs/source/code/PQAnalysis.io.energy_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.io.formats.rst delete mode 100644 docs/source/code/PQAnalysis.io.gen_file.api.rst delete mode 100644 docs/source/code/PQAnalysis.io.gen_file.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.io.gen_file.gen_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.gen_file.gen_file_writer.rst delete mode 100644 docs/source/code/PQAnalysis.io.gen_file.rst delete mode 100644 docs/source/code/PQAnalysis.io.info_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.formats.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.input_file_parser.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.pq.output_files.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.pq.pq_input_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.pq.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.rst delete mode 100644 docs/source/code/PQAnalysis.io.input_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.moldescriptor_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.nep.nep_writer.rst delete mode 100644 docs/source/code/PQAnalysis.io.nep.rst delete mode 100644 docs/source/code/PQAnalysis.io.optimizer_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.restart_file.api.rst delete mode 100644 docs/source/code/PQAnalysis.io.restart_file.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.io.restart_file.restart_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.restart_file.restart_writer.rst delete mode 100644 docs/source/code/PQAnalysis.io.restart_file.rst delete mode 100644 docs/source/code/PQAnalysis.io.rst delete mode 100644 docs/source/code/PQAnalysis.io.topology_file.api.rst delete mode 100644 docs/source/code/PQAnalysis.io.topology_file.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.io.topology_file.rst delete mode 100644 docs/source/code/PQAnalysis.io.topology_file.topology_file_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.topology_file.topology_file_writer.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.api.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.frame_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.raw_frame_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.trajectory_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.traj_file.trajectory_writer.rst delete mode 100644 docs/source/code/PQAnalysis.io.virial.api.rst delete mode 100644 docs/source/code/PQAnalysis.io.virial.rst delete mode 100644 docs/source/code/PQAnalysis.io.virial.virial_reader.rst delete mode 100644 docs/source/code/PQAnalysis.io.write_api.rst delete mode 100644 docs/source/code/PQAnalysis.physical_data.energy.rst delete mode 100644 docs/source/code/PQAnalysis.physical_data.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.physical_data.rst delete mode 100644 docs/source/code/PQAnalysis.rst delete mode 100644 docs/source/code/PQAnalysis.tools.add_molecule.rst delete mode 100644 docs/source/code/PQAnalysis.tools.rst delete mode 100644 docs/source/code/PQAnalysis.tools.traj_to_com_traj.rst delete mode 100644 docs/source/code/PQAnalysis.topology.api.rst delete mode 100644 docs/source/code/PQAnalysis.topology.bonded_topology.angle.rst delete mode 100644 docs/source/code/PQAnalysis.topology.bonded_topology.bond.rst delete mode 100644 docs/source/code/PQAnalysis.topology.bonded_topology.bonded_topology.rst delete mode 100644 docs/source/code/PQAnalysis.topology.bonded_topology.dihedral.rst delete mode 100644 docs/source/code/PQAnalysis.topology.bonded_topology.rst delete mode 100644 docs/source/code/PQAnalysis.topology.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.topology.rst delete mode 100644 docs/source/code/PQAnalysis.topology.selection.rst delete mode 100644 docs/source/code/PQAnalysis.topology.shake_topology.rst delete mode 100644 docs/source/code/PQAnalysis.topology.topology.rst delete mode 100644 docs/source/code/PQAnalysis.traj.api.rst delete mode 100644 docs/source/code/PQAnalysis.traj.exceptions.rst delete mode 100644 docs/source/code/PQAnalysis.traj.formats.rst delete mode 100644 docs/source/code/PQAnalysis.traj.rst delete mode 100644 docs/source/code/PQAnalysis.traj.trajectory.rst delete mode 100644 docs/source/code/PQAnalysis.type_checking.rst delete mode 100644 docs/source/code/PQAnalysis.types.rst delete mode 100644 docs/source/code/PQAnalysis.utils.common.rst delete mode 100644 docs/source/code/PQAnalysis.utils.custom_logging.rst delete mode 100644 docs/source/code/PQAnalysis.utils.decorators.rst delete mode 100644 docs/source/code/PQAnalysis.utils.files.rst delete mode 100644 docs/source/code/PQAnalysis.utils.random.rst delete mode 100644 docs/source/code/PQAnalysis.utils.rst delete mode 100644 docs/source/code/PQAnalysis.utils.units.rst delete mode 100644 docs/source/reference/index.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index add34a8d..3c0c1171 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -44,6 +44,10 @@ jobs: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: + - name: Configure GitHub Pages + uses: actions/configure-pages@v5 + with: + enablement: true - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index fb29d664..32d3e87e 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ build/ *.cpython-*.so PQAnalysis/analysis/msd/_msd_kernel.c PQAnalysis/analysis/vacf/_vacf_kernel.c +PQAnalysis/analysis/momentum/_momentum_kernel.c PQAnalysis/analysis/rdf/_rdf_kernel.c PQAnalysis/io/traj_file/_slab_parser.c @@ -34,3 +35,7 @@ venv.bak/ .mypy_cache .pytest_cache .qodo + +# generated api documentation (better-apidoc regenerates at every docs build) +docs/source/code/ +docs/build/ diff --git a/docs/autodoc.sh b/docs/autodoc.sh deleted file mode 100755 index c301ea0c..00000000 --- a/docs/autodoc.sh +++ /dev/null @@ -1 +0,0 @@ -sphinx-apidoc ../PQAnalysis -o source/code -f -t source/_templates -e -M --no-toc diff --git a/docs/source/code/PQAnalysis.analysis.rdf.api.rst b/docs/source/code/PQAnalysis.analysis.rdf.api.rst deleted file mode 100644 index cb5f44a0..00000000 --- a/docs/source/code/PQAnalysis.analysis.rdf.api.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -api -================================== - -.. currentmodule:: PQAnalysis.analysis.rdf.api - -.. automodule:: PQAnalysis.analysis.rdf.api - :members: rdf - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - rdf - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.rdf.exceptions.rst b/docs/source/code/PQAnalysis.analysis.rdf.exceptions.rst deleted file mode 100644 index 9a397b68..00000000 --- a/docs/source/code/PQAnalysis.analysis.rdf.exceptions.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -exceptions -========================================= - -.. currentmodule:: PQAnalysis.analysis.rdf.exceptions - -.. automodule:: PQAnalysis.analysis.rdf.exceptions - :members: RDFError, RDFWarning - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - RDFError - RDFWarning - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.rdf.rdf.rst b/docs/source/code/PQAnalysis.analysis.rdf.rdf.rst deleted file mode 100644 index cedf62ff..00000000 --- a/docs/source/code/PQAnalysis.analysis.rdf.rdf.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -rdf -================================== - -.. currentmodule:: PQAnalysis.analysis.rdf.rdf - -.. automodule:: PQAnalysis.analysis.rdf.rdf - :members: RDF, with_progress_bar - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - RDF - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.rdf.rdf_input_file_reader.rst b/docs/source/code/PQAnalysis.analysis.rdf.rdf_input_file_reader.rst deleted file mode 100644 index 6bfd206e..00000000 --- a/docs/source/code/PQAnalysis.analysis.rdf.rdf_input_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -rdf_input_file_reader -==================================================== - -.. currentmodule:: PQAnalysis.analysis.rdf.rdf_input_file_reader - -.. automodule:: PQAnalysis.analysis.rdf.rdf_input_file_reader - :members: RDFInputFileReader, input_keys_documentation - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - RDFInputFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.rdf.rdf_output_file_writer.rst b/docs/source/code/PQAnalysis.analysis.rdf.rdf_output_file_writer.rst deleted file mode 100644 index 6ac5e4f5..00000000 --- a/docs/source/code/PQAnalysis.analysis.rdf.rdf_output_file_writer.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -rdf_output_file_writer -===================================================== - -.. currentmodule:: PQAnalysis.analysis.rdf.rdf_output_file_writer - -.. automodule:: PQAnalysis.analysis.rdf.rdf_output_file_writer - :members: RDFDataWriter, RDFLogWriter - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - RDFDataWriter - RDFLogWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.rdf.rst b/docs/source/code/PQAnalysis.analysis.rdf.rst deleted file mode 100644 index 4a88bd93..00000000 --- a/docs/source/code/PQAnalysis.analysis.rdf.rst +++ /dev/null @@ -1,27 +0,0 @@ - -:autogenerated: - -analysis.rdf -=============================== - -.. automodule:: PQAnalysis.analysis.rdf - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.analysis.rdf.api - PQAnalysis.analysis.rdf.exceptions - PQAnalysis.analysis.rdf.rdf - PQAnalysis.analysis.rdf.rdf_input_file_reader - PQAnalysis.analysis.rdf.rdf_output_file_writer - - - - - diff --git a/docs/source/code/PQAnalysis.analysis.rst b/docs/source/code/PQAnalysis.analysis.rst deleted file mode 100644 index 7cdae7f9..00000000 --- a/docs/source/code/PQAnalysis.analysis.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -analysis -=========================== - -.. automodule:: PQAnalysis.analysis - - - - - Subpackages - ----------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.analysis.rdf - PQAnalysis.analysis.vibrational - - - - - diff --git a/docs/source/code/PQAnalysis.analysis.vibrational.api.rst b/docs/source/code/PQAnalysis.analysis.vibrational.api.rst deleted file mode 100644 index 5c0492c5..00000000 --- a/docs/source/code/PQAnalysis.analysis.vibrational.api.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -api -========================================== - -.. currentmodule:: PQAnalysis.analysis.vibrational.api - -.. automodule:: PQAnalysis.analysis.vibrational.api - :members: vibrations - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - vibrations - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.vibrational.exceptions.rst b/docs/source/code/PQAnalysis.analysis.vibrational.exceptions.rst deleted file mode 100644 index 699cce02..00000000 --- a/docs/source/code/PQAnalysis.analysis.vibrational.exceptions.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -exceptions -================================================= - -.. currentmodule:: PQAnalysis.analysis.vibrational.exceptions - -.. automodule:: PQAnalysis.analysis.vibrational.exceptions - :members: VibrationalAnalysisError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - VibrationalAnalysisError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.vibrational.rst b/docs/source/code/PQAnalysis.analysis.vibrational.rst deleted file mode 100644 index f6e8025f..00000000 --- a/docs/source/code/PQAnalysis.analysis.vibrational.rst +++ /dev/null @@ -1,60 +0,0 @@ - -:autogenerated: - -analysis.vibrational -======================================= - -.. automodule:: PQAnalysis.analysis.vibrational - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.analysis.vibrational.api - PQAnalysis.analysis.vibrational.exceptions - PQAnalysis.analysis.vibrational.vibrational_analysis - PQAnalysis.analysis.vibrational.vibrational_input_file_reader - - - - - Summary - ------- - - ``__all__`` Classes: - - - .. list-table:: - - * - :class:`VibrationalAnalysisInputFileReader ` - - A class to read input files for vibrational analysis. - * - :class:`VibrationalAnalysisResult ` - - Result container for a vibrational analysis. - - - ``__all__`` Functions: - - - .. list-table:: - - * - :func:`calculate ` - - Calculate wavenumbers, force constants, reduced masses and normal modes. - * - :func:`read_hessian_file ` - - Read a plain square Hessian matrix. - * - :func:`select_mode_indices ` - - Select mode indices from a user-facing one-based mode selection. - * - :func:`vibrations ` - - Run vibrational analysis from an input file. - * - :func:`write_calculate_output ` - - Write the tabular vibrational analysis output. - * - :func:`write_extxyz_modes ` - - Write selected normal modes to one extended XYZ file. - * - :func:`write_normal_modes ` - - Write normal modes in matrix form. - * - :func:`write_xyz_modes ` - - Write one sinusoidal XYZ trajectory per selected normal mode. diff --git a/docs/source/code/PQAnalysis.analysis.vibrational.vibrational_analysis.rst b/docs/source/code/PQAnalysis.analysis.vibrational.vibrational_analysis.rst deleted file mode 100644 index 4792b72c..00000000 --- a/docs/source/code/PQAnalysis.analysis.vibrational.vibrational_analysis.rst +++ /dev/null @@ -1,63 +0,0 @@ - -:autogenerated: - -vibrational_analysis -=========================================================== - -.. currentmodule:: PQAnalysis.analysis.vibrational.vibrational_analysis - -.. automodule:: PQAnalysis.analysis.vibrational.vibrational_analysis - :members: BOLTZMANN_EV_K, LINEAR_ROTATION_RTOL, MODE_THRESHOLD_CM, SPEED_OF_LIGHT_CM_S, VibrationalAnalysisResult, WAVENUMBER_TO_EV, calculate, calculate_from_system, center_to_com, force_constant, hessian_sign_factor, inertia_tensor, infrared_intensity, internal_coordinates, internal_subspace, mass_weighted_hessian, masses_matrix, mode_displacement, read_hessian_file, reduced_mass, rotational_modes, select_mode_indices, signed_sqrt, symmetrize_addition, transformation_matrix, translational_modes, wavenumber, write_calculate_output, write_extxyz_modes, write_normal_modes, write_xyz_modes - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - VibrationalAnalysisResult - - Functions: - - .. autosummary:: - :nosignatures: - - calculate - calculate_from_system - center_to_com - force_constant - hessian_sign_factor - inertia_tensor - infrared_intensity - internal_coordinates - internal_subspace - mass_weighted_hessian - masses_matrix - mode_displacement - read_hessian_file - reduced_mass - rotational_modes - select_mode_indices - signed_sqrt - symmetrize_addition - transformation_matrix - translational_modes - wavenumber - write_calculate_output - write_extxyz_modes - write_normal_modes - write_xyz_modes - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.analysis.vibrational.vibrational_input_file_reader.rst b/docs/source/code/PQAnalysis.analysis.vibrational.vibrational_input_file_reader.rst deleted file mode 100644 index c4fbb2e2..00000000 --- a/docs/source/code/PQAnalysis.analysis.vibrational.vibrational_input_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -vibrational_input_file_reader -==================================================================== - -.. currentmodule:: PQAnalysis.analysis.vibrational.vibrational_input_file_reader - -.. automodule:: PQAnalysis.analysis.vibrational.vibrational_input_file_reader - :members: VibrationalAnalysisInputFileReader, input_keys_documentation - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - VibrationalAnalysisInputFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.atomic_system.atomic_system.rst b/docs/source/code/PQAnalysis.atomic_system.atomic_system.rst deleted file mode 100644 index b89fe1ef..00000000 --- a/docs/source/code/PQAnalysis.atomic_system.atomic_system.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -atomic_system -============================================= - -.. currentmodule:: PQAnalysis.atomic_system.atomic_system - -.. automodule:: PQAnalysis.atomic_system.atomic_system - :members: AtomicSystem - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - AtomicSystem - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.atomic_system.exceptions.rst b/docs/source/code/PQAnalysis.atomic_system.exceptions.rst deleted file mode 100644 index ea1a6d46..00000000 --- a/docs/source/code/PQAnalysis.atomic_system.exceptions.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -exceptions -========================================== - -.. currentmodule:: PQAnalysis.atomic_system.exceptions - -.. automodule:: PQAnalysis.atomic_system.exceptions - :members: AtomicSystemError, AtomicSystemMassError, AtomicSystemPositionsError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - AtomicSystemError - AtomicSystemMassError - AtomicSystemPositionsError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.atomic_system.rst b/docs/source/code/PQAnalysis.atomic_system.rst deleted file mode 100644 index 0db96bd5..00000000 --- a/docs/source/code/PQAnalysis.atomic_system.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -atomic_system -================================ - -.. automodule:: PQAnalysis.atomic_system - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.atomic_system.atomic_system - PQAnalysis.atomic_system.exceptions - - - - - diff --git a/docs/source/code/PQAnalysis.cli.add_molecules.rst b/docs/source/code/PQAnalysis.cli.add_molecules.rst deleted file mode 100644 index 630ddf29..00000000 --- a/docs/source/code/PQAnalysis.cli.add_molecules.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -add_molecules -=================================== - -.. currentmodule:: PQAnalysis.cli.add_molecules - -.. automodule:: PQAnalysis.cli.add_molecules - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.build_nep_traj.rst b/docs/source/code/PQAnalysis.cli.build_nep_traj.rst deleted file mode 100644 index 819d2c6f..00000000 --- a/docs/source/code/PQAnalysis.cli.build_nep_traj.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -build_nep_traj -==================================== - -.. currentmodule:: PQAnalysis.cli.build_nep_traj - -.. automodule:: PQAnalysis.cli.build_nep_traj - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.continue_input.rst b/docs/source/code/PQAnalysis.cli.continue_input.rst deleted file mode 100644 index 7193d716..00000000 --- a/docs/source/code/PQAnalysis.cli.continue_input.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -continue_input -==================================== - -.. currentmodule:: PQAnalysis.cli.continue_input - -.. automodule:: PQAnalysis.cli.continue_input - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.gen2xyz.rst b/docs/source/code/PQAnalysis.cli.gen2xyz.rst deleted file mode 100644 index dba78fc9..00000000 --- a/docs/source/code/PQAnalysis.cli.gen2xyz.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -gen2xyz -============================= - -.. currentmodule:: PQAnalysis.cli.gen2xyz - -.. automodule:: PQAnalysis.cli.gen2xyz - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.rdf.rst b/docs/source/code/PQAnalysis.cli.rdf.rst deleted file mode 100644 index 1ddee00b..00000000 --- a/docs/source/code/PQAnalysis.cli.rdf.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -rdf -========================= - -.. currentmodule:: PQAnalysis.cli.rdf - -.. automodule:: PQAnalysis.cli.rdf - :members: code_base_url, input_keys_documentation, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.rst b/docs/source/code/PQAnalysis.cli.rst deleted file mode 100644 index 5716de0a..00000000 --- a/docs/source/code/PQAnalysis.cli.rst +++ /dev/null @@ -1,31 +0,0 @@ - -:autogenerated: - -cli -====================== - -.. automodule:: PQAnalysis.cli - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.cli.add_molecules - PQAnalysis.cli.build_nep_traj - PQAnalysis.cli.continue_input - PQAnalysis.cli.gen2xyz - PQAnalysis.cli.rdf - PQAnalysis.cli.rst2xyz - PQAnalysis.cli.traj2box - PQAnalysis.cli.traj2qmcfc - PQAnalysis.cli.vibrations - PQAnalysis.cli.xyz2gen - - - - diff --git a/docs/source/code/PQAnalysis.cli.rst2xyz.rst b/docs/source/code/PQAnalysis.cli.rst2xyz.rst deleted file mode 100644 index d13d657f..00000000 --- a/docs/source/code/PQAnalysis.cli.rst2xyz.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -rst2xyz -============================= - -.. currentmodule:: PQAnalysis.cli.rst2xyz - -.. automodule:: PQAnalysis.cli.rst2xyz - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.traj2box.rst b/docs/source/code/PQAnalysis.cli.traj2box.rst deleted file mode 100644 index 13adaba4..00000000 --- a/docs/source/code/PQAnalysis.cli.traj2box.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -traj2box -============================== - -.. currentmodule:: PQAnalysis.cli.traj2box - -.. automodule:: PQAnalysis.cli.traj2box - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.traj2qmcfc.rst b/docs/source/code/PQAnalysis.cli.traj2qmcfc.rst deleted file mode 100644 index d89bc25d..00000000 --- a/docs/source/code/PQAnalysis.cli.traj2qmcfc.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -traj2qmcfc -================================ - -.. currentmodule:: PQAnalysis.cli.traj2qmcfc - -.. automodule:: PQAnalysis.cli.traj2qmcfc - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.vibrations.rst b/docs/source/code/PQAnalysis.cli.vibrations.rst deleted file mode 100644 index 2deb0a50..00000000 --- a/docs/source/code/PQAnalysis.cli.vibrations.rst +++ /dev/null @@ -1,39 +0,0 @@ - -:autogenerated: - -vibrations -================================ - -.. currentmodule:: PQAnalysis.cli.vibrations - -.. automodule:: PQAnalysis.cli.vibrations - :members: VibrationsCLI, code_base_url, input_keys_documentation, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - VibrationsCLI - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.xyz2gen.rst b/docs/source/code/PQAnalysis.cli.xyz2gen.rst deleted file mode 100644 index d3c475c8..00000000 --- a/docs/source/code/PQAnalysis.cli.xyz2gen.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -xyz2gen -============================= - -.. currentmodule:: PQAnalysis.cli.xyz2gen - -.. automodule:: PQAnalysis.cli.xyz2gen - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.cli.xyz2rst.rst b/docs/source/code/PQAnalysis.cli.xyz2rst.rst deleted file mode 100644 index 8408b25f..00000000 --- a/docs/source/code/PQAnalysis.cli.xyz2rst.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -xyz2rst -============================= - -.. currentmodule:: PQAnalysis.cli.xyz2rst - -.. automodule:: PQAnalysis.cli.xyz2rst - :members: code_base_url, main - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - main - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.config.rst b/docs/source/code/PQAnalysis.config.rst deleted file mode 100644 index 345832f8..00000000 --- a/docs/source/code/PQAnalysis.config.rst +++ /dev/null @@ -1,25 +0,0 @@ - -:autogenerated: - -config -======================== - -.. currentmodule:: PQAnalysis.config - -.. automodule:: PQAnalysis.config - :members: PQ_docs_url, base_url, code_base_url, log_file_name, use_log_file, with_progress_bar - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.api.rst b/docs/source/code/PQAnalysis.core.api.rst deleted file mode 100644 index fba850a7..00000000 --- a/docs/source/code/PQAnalysis.core.api.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -api -========================== - -.. currentmodule:: PQAnalysis.core.api - -.. automodule:: PQAnalysis.core.api - :members: distance - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - distance - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.atom.atom.rst b/docs/source/code/PQAnalysis.core.atom.atom.rst deleted file mode 100644 index 38e63119..00000000 --- a/docs/source/code/PQAnalysis.core.atom.atom.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -atom -================================ - -.. currentmodule:: PQAnalysis.core.atom.atom - -.. automodule:: PQAnalysis.core.atom.atom - :members: Atom, Atoms - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Atom - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.atom.element.rst b/docs/source/code/PQAnalysis.core.atom.element.rst deleted file mode 100644 index 5ba3a787..00000000 --- a/docs/source/code/PQAnalysis.core.atom.element.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -element -=================================== - -.. currentmodule:: PQAnalysis.core.atom.element - -.. automodule:: PQAnalysis.core.atom.element - :members: Element, Elements, atomicMasses, atomicNumbers, atomicNumbersReverse - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Element - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.atom.rst b/docs/source/code/PQAnalysis.core.atom.rst deleted file mode 100644 index d8157f31..00000000 --- a/docs/source/code/PQAnalysis.core.atom.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -core.atom -============================ - -.. automodule:: PQAnalysis.core.atom - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.core.atom.atom - PQAnalysis.core.atom.element - - - - - diff --git a/docs/source/code/PQAnalysis.core.cell.cell.rst b/docs/source/code/PQAnalysis.core.cell.cell.rst deleted file mode 100644 index 57cc9ae6..00000000 --- a/docs/source/code/PQAnalysis.core.cell.cell.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -cell -================================ - -.. currentmodule:: PQAnalysis.core.cell.cell - -.. automodule:: PQAnalysis.core.cell.cell - :members: Cell, Cells - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Cell - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.cell.rst b/docs/source/code/PQAnalysis.core.cell.rst deleted file mode 100644 index 9575632f..00000000 --- a/docs/source/code/PQAnalysis.core.cell.rst +++ /dev/null @@ -1,23 +0,0 @@ - -:autogenerated: - -core.cell -============================ - -.. automodule:: PQAnalysis.core.cell - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.core.cell.cell - - - - - diff --git a/docs/source/code/PQAnalysis.core.exceptions.rst b/docs/source/code/PQAnalysis.core.exceptions.rst deleted file mode 100644 index b364ad50..00000000 --- a/docs/source/code/PQAnalysis.core.exceptions.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -exceptions -================================= - -.. currentmodule:: PQAnalysis.core.exceptions - -.. automodule:: PQAnalysis.core.exceptions - :members: ElementNotFoundError, ResidueError, ResidueWarning - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - ElementNotFoundError - ResidueError - ResidueWarning - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.residue.rst b/docs/source/code/PQAnalysis.core.residue.rst deleted file mode 100644 index b7076cf1..00000000 --- a/docs/source/code/PQAnalysis.core.residue.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -residue -============================== - -.. currentmodule:: PQAnalysis.core.residue - -.. automodule:: PQAnalysis.core.residue - :members: QMResidue, Residue - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - QMResidue - Residue - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.core.rst b/docs/source/code/PQAnalysis.core.rst deleted file mode 100644 index 220bc9c0..00000000 --- a/docs/source/code/PQAnalysis.core.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -core -======================= - -.. automodule:: PQAnalysis.core - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.core.api - PQAnalysis.core.exceptions - PQAnalysis.core.residue - - Subpackages - ----------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.core.atom - PQAnalysis.core.cell - - - - - diff --git a/docs/source/code/PQAnalysis.exceptions.rst b/docs/source/code/PQAnalysis.exceptions.rst deleted file mode 100644 index b03b3377..00000000 --- a/docs/source/code/PQAnalysis.exceptions.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -exceptions -============================ - -.. currentmodule:: PQAnalysis.exceptions - -.. automodule:: PQAnalysis.exceptions - :members: BaseEnumFormatError, PQException, PQWarning - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - BaseEnumFormatError - PQException - PQWarning - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.formats.rst b/docs/source/code/PQAnalysis.formats.rst deleted file mode 100644 index 3d77a562..00000000 --- a/docs/source/code/PQAnalysis.formats.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -formats -========================= - -.. currentmodule:: PQAnalysis.formats - -.. automodule:: PQAnalysis.formats - :members: BaseEnumFormat - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - BaseEnumFormat - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.api.rst b/docs/source/code/PQAnalysis.io.api.rst deleted file mode 100644 index d2ecbce9..00000000 --- a/docs/source/code/PQAnalysis.io.api.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -api -======================== - -.. currentmodule:: PQAnalysis.io.api - -.. automodule:: PQAnalysis.io.api - :members: continue_input_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - continue_input_file - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.base.rst b/docs/source/code/PQAnalysis.io.base.rst deleted file mode 100644 index 33d90d68..00000000 --- a/docs/source/code/PQAnalysis.io.base.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -base -========================= - -.. currentmodule:: PQAnalysis.io.base - -.. automodule:: PQAnalysis.io.base - :members: BaseReader, BaseWriter - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - BaseReader - BaseWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.box_writer.rst b/docs/source/code/PQAnalysis.io.box_writer.rst deleted file mode 100644 index 6308d12f..00000000 --- a/docs/source/code/PQAnalysis.io.box_writer.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -box_writer -=============================== - -.. currentmodule:: PQAnalysis.io.box_writer - -.. automodule:: PQAnalysis.io.box_writer - :members: BoxWriter - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - BoxWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.conversion_api.rst b/docs/source/code/PQAnalysis.io.conversion_api.rst deleted file mode 100644 index 7e2521d9..00000000 --- a/docs/source/code/PQAnalysis.io.conversion_api.rst +++ /dev/null @@ -1,36 +0,0 @@ - -:autogenerated: - -conversion_api -=================================== - -.. currentmodule:: PQAnalysis.io.conversion_api - -.. automodule:: PQAnalysis.io.conversion_api - :members: gen2xyz, rst2xyz, traj2box, traj2qmcfc, xyz2gen - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - gen2xyz - rst2xyz - traj2box - traj2qmcfc - xyz2gen - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.energy_file_reader.rst b/docs/source/code/PQAnalysis.io.energy_file_reader.rst deleted file mode 100644 index 694604c7..00000000 --- a/docs/source/code/PQAnalysis.io.energy_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -energy_file_reader -======================================= - -.. currentmodule:: PQAnalysis.io.energy_file_reader - -.. automodule:: PQAnalysis.io.energy_file_reader - :members: EnergyFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - EnergyFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.exceptions.rst b/docs/source/code/PQAnalysis.io.exceptions.rst deleted file mode 100644 index f031b6fd..00000000 --- a/docs/source/code/PQAnalysis.io.exceptions.rst +++ /dev/null @@ -1,37 +0,0 @@ - -:autogenerated: - -exceptions -=============================== - -.. currentmodule:: PQAnalysis.io.exceptions - -.. automodule:: PQAnalysis.io.exceptions - :members: BoxFileFormatError, BoxWriterError, FileWritingModeError, MoldescriptorReaderError, OptimizerReaderError, OutputFileFormatError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - BoxFileFormatError - BoxWriterError - FileWritingModeError - MoldescriptorReaderError - OptimizerReaderError - OutputFileFormatError - - - - - - - - Reference - --------- diff --git a/docs/source/code/PQAnalysis.io.formats.rst b/docs/source/code/PQAnalysis.io.formats.rst deleted file mode 100644 index 0422f929..00000000 --- a/docs/source/code/PQAnalysis.io.formats.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -formats -============================ - -.. currentmodule:: PQAnalysis.io.formats - -.. automodule:: PQAnalysis.io.formats - :members: BoxFileFormat, FileWritingMode, OutputFileFormat - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - BoxFileFormat - FileWritingMode - OutputFileFormat - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.gen_file.api.rst b/docs/source/code/PQAnalysis.io.gen_file.api.rst deleted file mode 100644 index 4044490e..00000000 --- a/docs/source/code/PQAnalysis.io.gen_file.api.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -api -================================= - -.. currentmodule:: PQAnalysis.io.gen_file.api - -.. automodule:: PQAnalysis.io.gen_file.api - :members: read_gen_file, write_gen_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - read_gen_file - write_gen_file - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.gen_file.exceptions.rst b/docs/source/code/PQAnalysis.io.gen_file.exceptions.rst deleted file mode 100644 index 1748bce9..00000000 --- a/docs/source/code/PQAnalysis.io.gen_file.exceptions.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -exceptions -======================================== - -.. currentmodule:: PQAnalysis.io.gen_file.exceptions - -.. automodule:: PQAnalysis.io.gen_file.exceptions - :members: GenFileReaderError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - GenFileReaderError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.gen_file.gen_file_reader.rst b/docs/source/code/PQAnalysis.io.gen_file.gen_file_reader.rst deleted file mode 100644 index a5595574..00000000 --- a/docs/source/code/PQAnalysis.io.gen_file.gen_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -gen_file_reader -============================================= - -.. currentmodule:: PQAnalysis.io.gen_file.gen_file_reader - -.. automodule:: PQAnalysis.io.gen_file.gen_file_reader - :members: GenFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - GenFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.gen_file.gen_file_writer.rst b/docs/source/code/PQAnalysis.io.gen_file.gen_file_writer.rst deleted file mode 100644 index af5223a8..00000000 --- a/docs/source/code/PQAnalysis.io.gen_file.gen_file_writer.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -gen_file_writer -============================================= - -.. currentmodule:: PQAnalysis.io.gen_file.gen_file_writer - -.. automodule:: PQAnalysis.io.gen_file.gen_file_writer - :members: GenFileWriter - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - GenFileWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.gen_file.rst b/docs/source/code/PQAnalysis.io.gen_file.rst deleted file mode 100644 index dc5e0c3e..00000000 --- a/docs/source/code/PQAnalysis.io.gen_file.rst +++ /dev/null @@ -1,26 +0,0 @@ - -:autogenerated: - -io.gen_file -============================== - -.. automodule:: PQAnalysis.io.gen_file - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.gen_file.api - PQAnalysis.io.gen_file.exceptions - PQAnalysis.io.gen_file.gen_file_reader - PQAnalysis.io.gen_file.gen_file_writer - - - - - diff --git a/docs/source/code/PQAnalysis.io.info_file_reader.rst b/docs/source/code/PQAnalysis.io.info_file_reader.rst deleted file mode 100644 index a6c53461..00000000 --- a/docs/source/code/PQAnalysis.io.info_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -info_file_reader -===================================== - -.. currentmodule:: PQAnalysis.io.info_file_reader - -.. automodule:: PQAnalysis.io.info_file_reader - :members: InfoFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - InfoFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.exceptions.rst b/docs/source/code/PQAnalysis.io.input_file_reader.exceptions.rst deleted file mode 100644 index 281601fd..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.exceptions.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -exceptions -================================================= - -.. currentmodule:: PQAnalysis.io.input_file_reader.exceptions - -.. automodule:: PQAnalysis.io.input_file_reader.exceptions - :members: InputFileError, InputFileFormatError, InputFileWarning - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - InputFileError - InputFileFormatError - InputFileWarning - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.formats.rst b/docs/source/code/PQAnalysis.io.input_file_reader.formats.rst deleted file mode 100644 index e38dde57..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.formats.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -formats -============================================== - -.. currentmodule:: PQAnalysis.io.input_file_reader.formats - -.. automodule:: PQAnalysis.io.input_file_reader.formats - :members: InputFileFormat - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - InputFileFormat - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.input_file_parser.rst b/docs/source/code/PQAnalysis.io.input_file_reader.input_file_parser.rst deleted file mode 100644 index d7472345..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.input_file_parser.rst +++ /dev/null @@ -1,36 +0,0 @@ - -:autogenerated: - -input_file_parser -======================================================== - -.. currentmodule:: PQAnalysis.io.input_file_reader.input_file_parser - -.. automodule:: PQAnalysis.io.input_file_reader.input_file_parser - :members: ComposedDatatypesTransformer, InputDictionary, InputFileParser, InputFileVisitor, PrimitiveTransformer - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - ComposedDatatypesTransformer - InputDictionary - InputFileParser - InputFileVisitor - PrimitiveTransformer - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.pq.output_files.rst b/docs/source/code/PQAnalysis.io.input_file_reader.pq.output_files.rst deleted file mode 100644 index f6f87bee..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.pq.output_files.rst +++ /dev/null @@ -1,16 +0,0 @@ - -:autogenerated: - -output_files -====================================================== - -.. currentmodule:: PQAnalysis.io.input_file_reader.pq.output_files - -.. automodule:: PQAnalysis.io.input_file_reader.pq.output_files - - - - - - - diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.pq.pq_input_file_reader.rst b/docs/source/code/PQAnalysis.io.input_file_reader.pq.pq_input_file_reader.rst deleted file mode 100644 index 1823a69e..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.pq.pq_input_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -pq_input_file_reader -============================================================== - -.. currentmodule:: PQAnalysis.io.input_file_reader.pq.pq_input_file_reader - -.. automodule:: PQAnalysis.io.input_file_reader.pq.pq_input_file_reader - :members: PQInputFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - PQInputFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.pq.rst b/docs/source/code/PQAnalysis.io.input_file_reader.pq.rst deleted file mode 100644 index 2297a2bd..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.pq.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -io.input_file_reader.pq -========================================== - -.. automodule:: PQAnalysis.io.input_file_reader.pq - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.input_file_reader.pq.output_files - PQAnalysis.io.input_file_reader.pq.pq_input_file_reader - - - - - diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader.rst b/docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader.rst deleted file mode 100644 index 3a849d5c..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -pqanalysis_input_file_reader -=============================================================================== - -.. currentmodule:: PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader - -.. automodule:: PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader - :members: PQAnalysisInputFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - PQAnalysisInputFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.rst b/docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.rst deleted file mode 100644 index 5f472040..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.pq_analysis.rst +++ /dev/null @@ -1,23 +0,0 @@ - -:autogenerated: - -io.input_file_reader.pq_analysis -=================================================== - -.. automodule:: PQAnalysis.io.input_file_reader.pq_analysis - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.input_file_reader.pq_analysis.pqanalysis_input_file_reader - - - - - diff --git a/docs/source/code/PQAnalysis.io.input_file_reader.rst b/docs/source/code/PQAnalysis.io.input_file_reader.rst deleted file mode 100644 index c7b496f4..00000000 --- a/docs/source/code/PQAnalysis.io.input_file_reader.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -io.input_file_reader -======================================= - -.. automodule:: PQAnalysis.io.input_file_reader - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.input_file_reader.exceptions - PQAnalysis.io.input_file_reader.formats - PQAnalysis.io.input_file_reader.input_file_parser - - Subpackages - ----------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.input_file_reader.pq - PQAnalysis.io.input_file_reader.pq_analysis - - - - - diff --git a/docs/source/code/PQAnalysis.io.moldescriptor_reader.rst b/docs/source/code/PQAnalysis.io.moldescriptor_reader.rst deleted file mode 100644 index 118ae895..00000000 --- a/docs/source/code/PQAnalysis.io.moldescriptor_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -moldescriptor_reader -========================================= - -.. currentmodule:: PQAnalysis.io.moldescriptor_reader - -.. automodule:: PQAnalysis.io.moldescriptor_reader - :members: MoldescriptorReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - MoldescriptorReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.nep.nep_writer.rst b/docs/source/code/PQAnalysis.io.nep.nep_writer.rst deleted file mode 100644 index 68fc04d7..00000000 --- a/docs/source/code/PQAnalysis.io.nep.nep_writer.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -nep_writer -=================================== - -.. currentmodule:: PQAnalysis.io.nep.nep_writer - -.. automodule:: PQAnalysis.io.nep.nep_writer - :members: NEPWriter, eV, kcal_per_mol - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - NEPWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.nep.rst b/docs/source/code/PQAnalysis.io.nep.rst deleted file mode 100644 index 326535a2..00000000 --- a/docs/source/code/PQAnalysis.io.nep.rst +++ /dev/null @@ -1,23 +0,0 @@ - -:autogenerated: - -io.nep -========================= - -.. automodule:: PQAnalysis.io.nep - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.nep.nep_writer - - - - - diff --git a/docs/source/code/PQAnalysis.io.optimizer_file_reader.rst b/docs/source/code/PQAnalysis.io.optimizer_file_reader.rst deleted file mode 100644 index d712795d..00000000 --- a/docs/source/code/PQAnalysis.io.optimizer_file_reader.rst +++ /dev/null @@ -1,37 +0,0 @@ - -:autogenerated: - -optimizer_file_reader -========================================== - -.. currentmodule:: PQAnalysis.io.optimizer_file_reader - -.. automodule:: PQAnalysis.io.optimizer_file_reader - :members: OptimizerFileReader, read_optimizer_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - OptimizerFileReader - - Functions: - - .. autosummary:: - :nosignatures: - - read_optimizer_file - - - - - - Reference - --------- diff --git a/docs/source/code/PQAnalysis.io.restart_file.api.rst b/docs/source/code/PQAnalysis.io.restart_file.api.rst deleted file mode 100644 index 1a935663..00000000 --- a/docs/source/code/PQAnalysis.io.restart_file.api.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -api -===================================== - -.. currentmodule:: PQAnalysis.io.restart_file.api - -.. automodule:: PQAnalysis.io.restart_file.api - :members: read_restart_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - read_restart_file - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.restart_file.exceptions.rst b/docs/source/code/PQAnalysis.io.restart_file.exceptions.rst deleted file mode 100644 index 65d13245..00000000 --- a/docs/source/code/PQAnalysis.io.restart_file.exceptions.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -exceptions -============================================ - -.. currentmodule:: PQAnalysis.io.restart_file.exceptions - -.. automodule:: PQAnalysis.io.restart_file.exceptions - :members: RestartFileReaderError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - RestartFileReaderError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.restart_file.restart_reader.rst b/docs/source/code/PQAnalysis.io.restart_file.restart_reader.rst deleted file mode 100644 index 498e6908..00000000 --- a/docs/source/code/PQAnalysis.io.restart_file.restart_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -restart_reader -================================================ - -.. currentmodule:: PQAnalysis.io.restart_file.restart_reader - -.. automodule:: PQAnalysis.io.restart_file.restart_reader - :members: RestartFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - RestartFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.restart_file.restart_writer.rst b/docs/source/code/PQAnalysis.io.restart_file.restart_writer.rst deleted file mode 100644 index 946a54be..00000000 --- a/docs/source/code/PQAnalysis.io.restart_file.restart_writer.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -restart_writer -================================================ - -.. currentmodule:: PQAnalysis.io.restart_file.restart_writer - -.. automodule:: PQAnalysis.io.restart_file.restart_writer - :members: RestartFileWriter - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - RestartFileWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.restart_file.rst b/docs/source/code/PQAnalysis.io.restart_file.rst deleted file mode 100644 index 4a7a0e11..00000000 --- a/docs/source/code/PQAnalysis.io.restart_file.rst +++ /dev/null @@ -1,26 +0,0 @@ - -:autogenerated: - -io.restart_file -================================== - -.. automodule:: PQAnalysis.io.restart_file - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.restart_file.api - PQAnalysis.io.restart_file.exceptions - PQAnalysis.io.restart_file.restart_reader - PQAnalysis.io.restart_file.restart_writer - - - - - diff --git a/docs/source/code/PQAnalysis.io.rst b/docs/source/code/PQAnalysis.io.rst deleted file mode 100644 index 13571acd..00000000 --- a/docs/source/code/PQAnalysis.io.rst +++ /dev/null @@ -1,46 +0,0 @@ - -:autogenerated: - -io -===================== - -.. automodule:: PQAnalysis.io - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.api - PQAnalysis.io.base - PQAnalysis.io.box_writer - PQAnalysis.io.conversion_api - PQAnalysis.io.energy_file_reader - PQAnalysis.io.exceptions - PQAnalysis.io.formats - PQAnalysis.io.info_file_reader - PQAnalysis.io.moldescriptor_reader - PQAnalysis.io.optimizer_file_reader - PQAnalysis.io.write_api - - Subpackages - ----------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.gen_file - PQAnalysis.io.input_file_reader - PQAnalysis.io.nep - PQAnalysis.io.restart_file - PQAnalysis.io.topology_file - PQAnalysis.io.traj_file - PQAnalysis.io.virial - - - - diff --git a/docs/source/code/PQAnalysis.io.topology_file.api.rst b/docs/source/code/PQAnalysis.io.topology_file.api.rst deleted file mode 100644 index e0356741..00000000 --- a/docs/source/code/PQAnalysis.io.topology_file.api.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -api -====================================== - -.. currentmodule:: PQAnalysis.io.topology_file.api - -.. automodule:: PQAnalysis.io.topology_file.api - :members: read_topology_file, write_topology_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - read_topology_file - write_topology_file - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.topology_file.exceptions.rst b/docs/source/code/PQAnalysis.io.topology_file.exceptions.rst deleted file mode 100644 index af74782d..00000000 --- a/docs/source/code/PQAnalysis.io.topology_file.exceptions.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -exceptions -============================================= - -.. currentmodule:: PQAnalysis.io.topology_file.exceptions - -.. automodule:: PQAnalysis.io.topology_file.exceptions - :members: TopologyFileError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - TopologyFileError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.topology_file.rst b/docs/source/code/PQAnalysis.io.topology_file.rst deleted file mode 100644 index 05107970..00000000 --- a/docs/source/code/PQAnalysis.io.topology_file.rst +++ /dev/null @@ -1,26 +0,0 @@ - -:autogenerated: - -io.topology_file -=================================== - -.. automodule:: PQAnalysis.io.topology_file - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.topology_file.api - PQAnalysis.io.topology_file.exceptions - PQAnalysis.io.topology_file.topology_file_reader - PQAnalysis.io.topology_file.topology_file_writer - - - - - diff --git a/docs/source/code/PQAnalysis.io.topology_file.topology_file_reader.rst b/docs/source/code/PQAnalysis.io.topology_file.topology_file_reader.rst deleted file mode 100644 index 28625250..00000000 --- a/docs/source/code/PQAnalysis.io.topology_file.topology_file_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -topology_file_reader -======================================================= - -.. currentmodule:: PQAnalysis.io.topology_file.topology_file_reader - -.. automodule:: PQAnalysis.io.topology_file.topology_file_reader - :members: TopologyFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - TopologyFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.topology_file.topology_file_writer.rst b/docs/source/code/PQAnalysis.io.topology_file.topology_file_writer.rst deleted file mode 100644 index f622f9b1..00000000 --- a/docs/source/code/PQAnalysis.io.topology_file.topology_file_writer.rst +++ /dev/null @@ -1,48 +0,0 @@ - -:autogenerated: - -topology_file_writer -======================================================= - -.. currentmodule:: PQAnalysis.io.topology_file.topology_file_writer - -.. automodule:: PQAnalysis.io.topology_file.topology_file_writer - :members: TopologyFileWriter, get_angle_lines, get_bond_lines, get_dihedral_lines, get_improper_lines, get_shake_lines, write_angle_info, write_bond_info, write_dihedral_info, write_improper_info, write_shake_info - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - TopologyFileWriter - - Functions: - - .. autosummary:: - :nosignatures: - - get_angle_lines - get_bond_lines - get_dihedral_lines - get_improper_lines - get_shake_lines - write_angle_info - write_bond_info - write_dihedral_info - write_improper_info - write_shake_info - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.traj_file.api.rst b/docs/source/code/PQAnalysis.io.traj_file.api.rst deleted file mode 100644 index 6f205e73..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.api.rst +++ /dev/null @@ -1,35 +0,0 @@ - -:autogenerated: - -api -================================== - -.. currentmodule:: PQAnalysis.io.traj_file.api - -.. automodule:: PQAnalysis.io.traj_file.api - :members: calculate_frames_of_trajectory_file, read_trajectory, read_trajectory_generator, write_trajectory - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - calculate_frames_of_trajectory_file - read_trajectory - read_trajectory_generator - write_trajectory - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.traj_file.exceptions.rst b/docs/source/code/PQAnalysis.io.traj_file.exceptions.rst deleted file mode 100644 index 18fce6a6..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.exceptions.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -exceptions -========================================= - -.. currentmodule:: PQAnalysis.io.traj_file.exceptions - -.. automodule:: PQAnalysis.io.traj_file.exceptions - :members: FrameReaderError, TrajectoryReaderError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - FrameReaderError - TrajectoryReaderError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.traj_file.frame_reader.rst b/docs/source/code/PQAnalysis.io.traj_file.frame_reader.rst deleted file mode 100644 index 6ebd2c08..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.frame_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -frame_reader -=========================================== - -.. currentmodule:: PQAnalysis.io.traj_file.frame_reader - -.. automodule:: PQAnalysis.io.traj_file.frame_reader - :members: FrameReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - FrameReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.traj_file.raw_frame_reader.rst b/docs/source/code/PQAnalysis.io.traj_file.raw_frame_reader.rst deleted file mode 100644 index a8ec71b7..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.raw_frame_reader.rst +++ /dev/null @@ -1,26 +0,0 @@ - -:autogenerated: - -raw_frame_reader -================================================ - -.. currentmodule:: PQAnalysis.io.traj_file.raw_frame_reader - -.. automodule:: PQAnalysis.io.traj_file.raw_frame_reader - :members: RawTrajectoryReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - RawTrajectoryReader - - Reference - --------- diff --git a/docs/source/code/PQAnalysis.io.traj_file.rst b/docs/source/code/PQAnalysis.io.traj_file.rst deleted file mode 100644 index e0a8c9dc..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.rst +++ /dev/null @@ -1,27 +0,0 @@ - -:autogenerated: - -io.traj_file -=============================== - -.. automodule:: PQAnalysis.io.traj_file - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.traj_file.api - PQAnalysis.io.traj_file.exceptions - PQAnalysis.io.traj_file.frame_reader - PQAnalysis.io.traj_file.raw_frame_reader - PQAnalysis.io.traj_file.trajectory_reader - PQAnalysis.io.traj_file.trajectory_writer - - - - diff --git a/docs/source/code/PQAnalysis.io.traj_file.trajectory_reader.rst b/docs/source/code/PQAnalysis.io.traj_file.trajectory_reader.rst deleted file mode 100644 index 347cef5a..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.trajectory_reader.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -trajectory_reader -================================================ - -.. currentmodule:: PQAnalysis.io.traj_file.trajectory_reader - -.. automodule:: PQAnalysis.io.traj_file.trajectory_reader - :members: TrajectoryReader, with_progress_bar - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - TrajectoryReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.traj_file.trajectory_writer.rst b/docs/source/code/PQAnalysis.io.traj_file.trajectory_writer.rst deleted file mode 100644 index 51a42095..00000000 --- a/docs/source/code/PQAnalysis.io.traj_file.trajectory_writer.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -trajectory_writer -================================================ - -.. currentmodule:: PQAnalysis.io.traj_file.trajectory_writer - -.. automodule:: PQAnalysis.io.traj_file.trajectory_writer - :members: TrajectoryWriter - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - TrajectoryWriter - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.virial.api.rst b/docs/source/code/PQAnalysis.io.virial.api.rst deleted file mode 100644 index 6b4abe08..00000000 --- a/docs/source/code/PQAnalysis.io.virial.api.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -api -=============================== - -.. currentmodule:: PQAnalysis.io.virial.api - -.. automodule:: PQAnalysis.io.virial.api - :members: read_stress_file, read_virial_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - read_stress_file - read_virial_file - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.virial.rst b/docs/source/code/PQAnalysis.io.virial.rst deleted file mode 100644 index 8ab95baf..00000000 --- a/docs/source/code/PQAnalysis.io.virial.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -io.virial -============================ - -.. automodule:: PQAnalysis.io.virial - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.io.virial.api - PQAnalysis.io.virial.virial_reader - - - - - diff --git a/docs/source/code/PQAnalysis.io.virial.virial_reader.rst b/docs/source/code/PQAnalysis.io.virial.virial_reader.rst deleted file mode 100644 index 4b6489c2..00000000 --- a/docs/source/code/PQAnalysis.io.virial.virial_reader.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -virial_reader -========================================= - -.. currentmodule:: PQAnalysis.io.virial.virial_reader - -.. automodule:: PQAnalysis.io.virial.virial_reader - :members: StressFileReader, VirialFileReader - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - StressFileReader - VirialFileReader - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.io.write_api.rst b/docs/source/code/PQAnalysis.io.write_api.rst deleted file mode 100644 index 752fc709..00000000 --- a/docs/source/code/PQAnalysis.io.write_api.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -write_api -============================== - -.. currentmodule:: PQAnalysis.io.write_api - -.. automodule:: PQAnalysis.io.write_api - :members: write, write_box - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - write - write_box - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.physical_data.energy.rst b/docs/source/code/PQAnalysis.physical_data.energy.rst deleted file mode 100644 index 505b18bd..00000000 --- a/docs/source/code/PQAnalysis.physical_data.energy.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -energy -====================================== - -.. currentmodule:: PQAnalysis.physical_data.energy - -.. automodule:: PQAnalysis.physical_data.energy - :members: Energy - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Energy - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.physical_data.exceptions.rst b/docs/source/code/PQAnalysis.physical_data.exceptions.rst deleted file mode 100644 index ede07c81..00000000 --- a/docs/source/code/PQAnalysis.physical_data.exceptions.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -exceptions -========================================== - -.. currentmodule:: PQAnalysis.physical_data.exceptions - -.. automodule:: PQAnalysis.physical_data.exceptions - :members: EnergyError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - EnergyError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.physical_data.rst b/docs/source/code/PQAnalysis.physical_data.rst deleted file mode 100644 index cb402127..00000000 --- a/docs/source/code/PQAnalysis.physical_data.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -physical_data -================================ - -.. automodule:: PQAnalysis.physical_data - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.physical_data.energy - PQAnalysis.physical_data.exceptions - - - - - diff --git a/docs/source/code/PQAnalysis.rst b/docs/source/code/PQAnalysis.rst deleted file mode 100644 index 4c5c7fe5..00000000 --- a/docs/source/code/PQAnalysis.rst +++ /dev/null @@ -1,52 +0,0 @@ - -:autogenerated: - - -================== - -.. automodule:: PQAnalysis - :members: execution_start_time, log_file_env_var, logging_env_var - :undoc-members: - :show-inheritance: - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.config - PQAnalysis.exceptions - PQAnalysis.formats - PQAnalysis.type_checking - PQAnalysis.types - - Subpackages - ----------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.analysis - PQAnalysis.atomic_system - PQAnalysis.cli - PQAnalysis.core - PQAnalysis.io - PQAnalysis.physical_data - PQAnalysis.tools - PQAnalysis.topology - PQAnalysis.traj - PQAnalysis.utils - - - - - Summary - ------- - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.tools.add_molecule.rst b/docs/source/code/PQAnalysis.tools.add_molecule.rst deleted file mode 100644 index 6dca2cf1..00000000 --- a/docs/source/code/PQAnalysis.tools.add_molecule.rst +++ /dev/null @@ -1,40 +0,0 @@ - -:autogenerated: - -add_molecule -==================================== - -.. currentmodule:: PQAnalysis.tools.add_molecule - -.. automodule:: PQAnalysis.tools.add_molecule - :members: AddMolecule, add_molecule, check_topology_args - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - AddMolecule - - Functions: - - .. autosummary:: - :nosignatures: - - add_molecule - check_topology_args - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.tools.rst b/docs/source/code/PQAnalysis.tools.rst deleted file mode 100644 index 2eb1bb6d..00000000 --- a/docs/source/code/PQAnalysis.tools.rst +++ /dev/null @@ -1,24 +0,0 @@ - -:autogenerated: - -tools -======================== - -.. automodule:: PQAnalysis.tools - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.tools.add_molecule - PQAnalysis.tools.traj_to_com_traj - - - - - diff --git a/docs/source/code/PQAnalysis.tools.traj_to_com_traj.rst b/docs/source/code/PQAnalysis.tools.traj_to_com_traj.rst deleted file mode 100644 index 6eacc4dd..00000000 --- a/docs/source/code/PQAnalysis.tools.traj_to_com_traj.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -traj_to_com_traj -======================================== - -.. currentmodule:: PQAnalysis.tools.traj_to_com_traj - -.. automodule:: PQAnalysis.tools.traj_to_com_traj - :members: traj_to_com_traj - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - traj_to_com_traj - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.api.rst b/docs/source/code/PQAnalysis.topology.api.rst deleted file mode 100644 index fc6fea58..00000000 --- a/docs/source/code/PQAnalysis.topology.api.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -api -============================== - -.. currentmodule:: PQAnalysis.topology.api - -.. automodule:: PQAnalysis.topology.api - :members: generate_shake_topology_file, select_from_restart_file, selection_from_restart_file_as_list - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - generate_shake_topology_file - select_from_restart_file - selection_from_restart_file_as_list - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.bonded_topology.angle.rst b/docs/source/code/PQAnalysis.topology.bonded_topology.angle.rst deleted file mode 100644 index 0f8b1472..00000000 --- a/docs/source/code/PQAnalysis.topology.bonded_topology.angle.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -angle -================================================ - -.. currentmodule:: PQAnalysis.topology.bonded_topology.angle - -.. automodule:: PQAnalysis.topology.bonded_topology.angle - :members: Angle - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Angle - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.bonded_topology.bond.rst b/docs/source/code/PQAnalysis.topology.bonded_topology.bond.rst deleted file mode 100644 index 9dbb053d..00000000 --- a/docs/source/code/PQAnalysis.topology.bonded_topology.bond.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -bond -=============================================== - -.. currentmodule:: PQAnalysis.topology.bonded_topology.bond - -.. automodule:: PQAnalysis.topology.bonded_topology.bond - :members: Bond - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Bond - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.bonded_topology.bonded_topology.rst b/docs/source/code/PQAnalysis.topology.bonded_topology.bonded_topology.rst deleted file mode 100644 index e413b839..00000000 --- a/docs/source/code/PQAnalysis.topology.bonded_topology.bonded_topology.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -bonded_topology -========================================================== - -.. currentmodule:: PQAnalysis.topology.bonded_topology.bonded_topology - -.. automodule:: PQAnalysis.topology.bonded_topology.bonded_topology - :members: BondedTopology - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - BondedTopology - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.bonded_topology.dihedral.rst b/docs/source/code/PQAnalysis.topology.bonded_topology.dihedral.rst deleted file mode 100644 index 1b604bfc..00000000 --- a/docs/source/code/PQAnalysis.topology.bonded_topology.dihedral.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -dihedral -=================================================== - -.. currentmodule:: PQAnalysis.topology.bonded_topology.dihedral - -.. automodule:: PQAnalysis.topology.bonded_topology.dihedral - :members: Dihedral - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Dihedral - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.bonded_topology.rst b/docs/source/code/PQAnalysis.topology.bonded_topology.rst deleted file mode 100644 index 1bdb1db7..00000000 --- a/docs/source/code/PQAnalysis.topology.bonded_topology.rst +++ /dev/null @@ -1,26 +0,0 @@ - -:autogenerated: - -topology.bonded_topology -=========================================== - -.. automodule:: PQAnalysis.topology.bonded_topology - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.topology.bonded_topology.angle - PQAnalysis.topology.bonded_topology.bond - PQAnalysis.topology.bonded_topology.bonded_topology - PQAnalysis.topology.bonded_topology.dihedral - - - - - diff --git a/docs/source/code/PQAnalysis.topology.exceptions.rst b/docs/source/code/PQAnalysis.topology.exceptions.rst deleted file mode 100644 index d4281c45..00000000 --- a/docs/source/code/PQAnalysis.topology.exceptions.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -exceptions -===================================== - -.. currentmodule:: PQAnalysis.topology.exceptions - -.. automodule:: PQAnalysis.topology.exceptions - :members: TopologyError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - TopologyError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.rst b/docs/source/code/PQAnalysis.topology.rst deleted file mode 100644 index ab8ae508..00000000 --- a/docs/source/code/PQAnalysis.topology.rst +++ /dev/null @@ -1,35 +0,0 @@ - -:autogenerated: - -topology -=========================== - -.. automodule:: PQAnalysis.topology - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.topology.api - PQAnalysis.topology.exceptions - PQAnalysis.topology.selection - PQAnalysis.topology.shake_topology - PQAnalysis.topology.topology - - Subpackages - ----------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.topology.bonded_topology - - - - - diff --git a/docs/source/code/PQAnalysis.topology.selection.rst b/docs/source/code/PQAnalysis.topology.selection.rst deleted file mode 100644 index 3e5698ae..00000000 --- a/docs/source/code/PQAnalysis.topology.selection.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -selection -==================================== - -.. currentmodule:: PQAnalysis.topology.selection - -.. automodule:: PQAnalysis.topology.selection - :members: Selection, SelectionCompatible, SelectionTransformer, SelectionVisitor - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Selection - SelectionTransformer - SelectionVisitor - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.shake_topology.rst b/docs/source/code/PQAnalysis.topology.shake_topology.rst deleted file mode 100644 index 595fd545..00000000 --- a/docs/source/code/PQAnalysis.topology.shake_topology.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -shake_topology -========================================= - -.. currentmodule:: PQAnalysis.topology.shake_topology - -.. automodule:: PQAnalysis.topology.shake_topology - :members: ShakeTopologyGenerator - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - ShakeTopologyGenerator - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.topology.topology.rst b/docs/source/code/PQAnalysis.topology.topology.rst deleted file mode 100644 index a42958c5..00000000 --- a/docs/source/code/PQAnalysis.topology.topology.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -topology -=================================== - -.. currentmodule:: PQAnalysis.topology.topology - -.. automodule:: PQAnalysis.topology.topology - :members: Topology - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Topology - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.traj.api.rst b/docs/source/code/PQAnalysis.traj.api.rst deleted file mode 100644 index 71407364..00000000 --- a/docs/source/code/PQAnalysis.traj.api.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -api -========================== - -.. currentmodule:: PQAnalysis.traj.api - -.. automodule:: PQAnalysis.traj.api - :members: check_trajectory_pbc, check_trajectory_vacuum - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - check_trajectory_pbc - check_trajectory_vacuum - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.traj.exceptions.rst b/docs/source/code/PQAnalysis.traj.exceptions.rst deleted file mode 100644 index c2827e17..00000000 --- a/docs/source/code/PQAnalysis.traj.exceptions.rst +++ /dev/null @@ -1,34 +0,0 @@ - -:autogenerated: - -exceptions -================================= - -.. currentmodule:: PQAnalysis.traj.exceptions - -.. automodule:: PQAnalysis.traj.exceptions - :members: MDEngineFormatError, TrajectoryError, TrajectoryFormatError - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - MDEngineFormatError - TrajectoryError - TrajectoryFormatError - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.traj.formats.rst b/docs/source/code/PQAnalysis.traj.formats.rst deleted file mode 100644 index b9431e69..00000000 --- a/docs/source/code/PQAnalysis.traj.formats.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -formats -============================== - -.. currentmodule:: PQAnalysis.traj.formats - -.. automodule:: PQAnalysis.traj.formats - :members: MDEngineFormat, TrajectoryFormat - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - MDEngineFormat - TrajectoryFormat - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.traj.rst b/docs/source/code/PQAnalysis.traj.rst deleted file mode 100644 index 0e336cab..00000000 --- a/docs/source/code/PQAnalysis.traj.rst +++ /dev/null @@ -1,26 +0,0 @@ - -:autogenerated: - -traj -======================= - -.. automodule:: PQAnalysis.traj - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.traj.api - PQAnalysis.traj.exceptions - PQAnalysis.traj.formats - PQAnalysis.traj.trajectory - - - - - diff --git a/docs/source/code/PQAnalysis.traj.trajectory.rst b/docs/source/code/PQAnalysis.traj.trajectory.rst deleted file mode 100644 index 2f357b4a..00000000 --- a/docs/source/code/PQAnalysis.traj.trajectory.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -trajectory -================================= - -.. currentmodule:: PQAnalysis.traj.trajectory - -.. automodule:: PQAnalysis.traj.trajectory - :members: Trajectory - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Classes: - - .. autosummary:: - :nosignatures: - - Trajectory - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.type_checking.rst b/docs/source/code/PQAnalysis.type_checking.rst deleted file mode 100644 index 41a0c404..00000000 --- a/docs/source/code/PQAnalysis.type_checking.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -type_checking -=============================== - -.. currentmodule:: PQAnalysis.type_checking - -.. automodule:: PQAnalysis.type_checking - :members: get_type_error_message - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - get_type_error_message - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.types.rst b/docs/source/code/PQAnalysis.types.rst deleted file mode 100644 index aa354114..00000000 --- a/docs/source/code/PQAnalysis.types.rst +++ /dev/null @@ -1,25 +0,0 @@ - -:autogenerated: - -types -======================= - -.. currentmodule:: PQAnalysis.types - -.. automodule:: PQAnalysis.types - :members: Np1DIntArray, Np1DNumberArray, Np2DIntArray, Np2DNumberArray, Np3x3NumberArray, NpnDNumberArray, PositiveInt, PositiveReal, Range - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.utils.common.rst b/docs/source/code/PQAnalysis.utils.common.rst deleted file mode 100644 index f043e13b..00000000 --- a/docs/source/code/PQAnalysis.utils.common.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -common -============================== - -.. currentmodule:: PQAnalysis.utils.common - -.. automodule:: PQAnalysis.utils.common - :members: print_header - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - print_header - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.utils.custom_logging.rst b/docs/source/code/PQAnalysis.utils.custom_logging.rst deleted file mode 100644 index 9a15f82b..00000000 --- a/docs/source/code/PQAnalysis.utils.custom_logging.rst +++ /dev/null @@ -1,48 +0,0 @@ - -:autogenerated: - -custom_logging -====================================== - -.. currentmodule:: PQAnalysis.utils.custom_logging - -.. automodule:: PQAnalysis.utils.custom_logging - :members: CustomColorFormatter, CustomFormatter, CustomLogger, CustomLoggerException, log_file_name, setup_logger, use_log_file - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Exceptions: - - .. autosummary:: - :nosignatures: - - CustomLoggerException - - Classes: - - .. autosummary:: - :nosignatures: - - CustomColorFormatter - CustomFormatter - CustomLogger - - Functions: - - .. autosummary:: - :nosignatures: - - setup_logger - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.utils.decorators.rst b/docs/source/code/PQAnalysis.utils.decorators.rst deleted file mode 100644 index 7eb7b8ac..00000000 --- a/docs/source/code/PQAnalysis.utils.decorators.rst +++ /dev/null @@ -1,33 +0,0 @@ - -:autogenerated: - -decorators -================================== - -.. currentmodule:: PQAnalysis.utils.decorators - -.. automodule:: PQAnalysis.utils.decorators - :members: count_decorator, get_arg_var_by_name - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - count_decorator - get_arg_var_by_name - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.utils.files.rst b/docs/source/code/PQAnalysis.utils.files.rst deleted file mode 100644 index f9d7f61a..00000000 --- a/docs/source/code/PQAnalysis.utils.files.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -files -============================= - -.. currentmodule:: PQAnalysis.utils.files - -.. automodule:: PQAnalysis.utils.files - :members: find_files_with_prefix - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - find_files_with_prefix - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.utils.random.rst b/docs/source/code/PQAnalysis.utils.random.rst deleted file mode 100644 index 0406eb4f..00000000 --- a/docs/source/code/PQAnalysis.utils.random.rst +++ /dev/null @@ -1,32 +0,0 @@ - -:autogenerated: - -random -============================== - -.. currentmodule:: PQAnalysis.utils.random - -.. automodule:: PQAnalysis.utils.random - :members: get_random_seed - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - Functions: - - .. autosummary:: - :nosignatures: - - get_random_seed - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/code/PQAnalysis.utils.rst b/docs/source/code/PQAnalysis.utils.rst deleted file mode 100644 index 0db4d79f..00000000 --- a/docs/source/code/PQAnalysis.utils.rst +++ /dev/null @@ -1,28 +0,0 @@ - -:autogenerated: - -utils -======================== - -.. automodule:: PQAnalysis.utils - - - - - Submodules - ---------- - - .. toctree:: - :maxdepth: 1 - - PQAnalysis.utils.common - PQAnalysis.utils.custom_logging - PQAnalysis.utils.decorators - PQAnalysis.utils.files - PQAnalysis.utils.random - PQAnalysis.utils.units - - - - - diff --git a/docs/source/code/PQAnalysis.utils.units.rst b/docs/source/code/PQAnalysis.utils.units.rst deleted file mode 100644 index 95c22f0d..00000000 --- a/docs/source/code/PQAnalysis.utils.units.rst +++ /dev/null @@ -1,25 +0,0 @@ - -:autogenerated: - -units -============================= - -.. currentmodule:: PQAnalysis.utils.units - -.. automodule:: PQAnalysis.utils.units - :members: J, J_per_mol, cal, eV, kcal, kcal_per_mol, mol - :undoc-members: - :show-inheritance: - :member-order: groupwise - - Summary - ------- - - - - - - - - Reference - --------- \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index cb0911fc..3047739e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -83,6 +83,10 @@ html_css_files = ["css/custom.css"] html_baseurl = "https://molarverse.github.io/PQAnalysis/" +# the deployed site is flat under html_baseurl, so the sitemap must not +# prefix the language or version (the sphinx-sitemap default scheme) +sitemap_url_scheme = "{link}" + html_theme_options = { "sidebar_hide_name": False, "light_css_variables": { diff --git a/docs/source/developerGuide/architecture.rst b/docs/source/developerGuide/architecture.rst index cb616ee6..24dffd49 100644 --- a/docs/source/developerGuide/architecture.rst +++ b/docs/source/developerGuide/architecture.rst @@ -65,7 +65,7 @@ compatibility or an explicit deprecation path. Numerical kernels ----------------- -RDF, MSD and VACF use compiled Cython kernels when available and NumPy/Python +RDF, MSD, VACF and momentum use compiled Cython kernels when available and NumPy/Python fallbacks otherwise. The compiled and fallback implementations must keep the same signature, normalization and edge-case behavior. A kernel change therefore requires tests of both implementations and a direct parity test between them. diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 955bd345..31031483 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -65,8 +65,10 @@ Existing analysis tables can be converted later: $ pqanalysis convert rdf.dat -o rdf.csv -o rdf.xvg -PQAnalysis refuses to overwrite an existing output unless replacement is -requested explicitly with ``--mode o``. +PQAnalysis refuses to overwrite an existing output file. Conversion and +support tools such as ``convert`` accept ``--mode o`` to request +replacement explicitly; the input-file driven analyses have no overwrite +flag, so move or delete the old output first. Next steps ---------- diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index 5fa0688d..3d7d310c 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -90,7 +90,7 @@ Simulation-support commands * - :ref:`add_molecules ` - Add molecular structures to an existing system * - :ref:`build_nep_traj ` - - Assemble a trajectory from nudged-elastic-band data + - Build Neuroevolution Potential (NEP) training and test trajectories Commands refuse unsafe output replacement by default. Consult each generated reference page for its supported writing modes and format-specific options. diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst deleted file mode 100644 index 3507129c..00000000 --- a/docs/source/reference/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -:orphan: - -Reference -========= - -Use the command reference for shell workflows and the Python API reference for -library integration. Scientific output definitions remain centralized so CLI -and API users share the same field names, units and normalization conventions. - -* :doc:`functions` lists public Python functions by task. -* :doc:`cli` covers analysis, conversion and simulation-support commands. -* :doc:`api` maps core classes and generated package modules. -* :ref:`analysisOutputFiles` specifies table fields, symbols, units and - serialization formats. diff --git a/pyproject.toml b/pyproject.toml index 3990becf..772f6589 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,7 +52,6 @@ docs = [ "sphinx>=8,<9", "sphinx-copybutton>=0.5,<1", "sphinx-sitemap", - "breathe", "myst-parser", "better-apidoc", "six", From 935e312259448fb77eddfccc9ffffe53460ac117 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Thu, 20 Aug 2026 17:53:51 +0200 Subject: [PATCH 09/12] docs: validate the command tables against the CLI registry Add a small local Sphinx extension with a pq-cli-table directive that renders the command tables of the command-line reference and validates them at build time: every listed name must exist in the pqanalysis command registry, and after reading all pages every registered command must be documented exactly once (prose-documented commands are marked with pq-cli-covered). A renamed, removed or newly added command now fails the strict documentation build instead of silently drifting out of the reference tables. The purpose texts stay editorial. --- docs/source/_ext/pq_cli_tables.py | 284 ++++++++++++++++++++++++++++++ docs/source/conf.py | 2 + docs/source/reference/cli.rst | 93 ++++------ 3 files changed, 319 insertions(+), 60 deletions(-) create mode 100644 docs/source/_ext/pq_cli_tables.py diff --git a/docs/source/_ext/pq_cli_tables.py b/docs/source/_ext/pq_cli_tables.py new file mode 100644 index 00000000..9391a05a --- /dev/null +++ b/docs/source/_ext/pq_cli_tables.py @@ -0,0 +1,284 @@ +""" +A small Sphinx extension that keeps the command-line reference in sync +with the code. + +The ``pq-cli-table`` directive renders a list-table of commands. Every +command name in the table body is validated against the registry in +:py:mod:`PQAnalysis.cli.main` at build time, so a renamed or removed +command fails the documentation build instead of leaving a stale table +row. The ``pq-cli-covered`` directive marks commands that are documented +in prose instead of a table. After the build has read every page, the +extension checks that each registered command was documented exactly +once and raises a warning (an error under ``-W``) for every command +that is missing from or duplicated in the documentation. + +Table rows use the form ``name -- purpose`` or +``name -- purpose -- primary input``; the purpose text is editorial, +while the command name and its cross reference come from the code. +""" + +import contextlib +import io + +from docutils import nodes +from docutils.parsers.rst import directives +from docutils.statemachine import ViewList +from sphinx.util import logging +from sphinx.util.docutils import SphinxDirective + +logger = logging.getLogger(__name__) + +_ROW_SEPARATOR = " -- " + + +def _registered_commands(): + """ + Returns the registered command names from the PQAnalysis CLI. + + The import prints the PQAnalysis header to stdout, which is + swallowed so that it does not clutter the Sphinx build output. + + Returns + ------- + set[str] + The names of all registered ``pqanalysis`` subcommands. + """ + with contextlib.redirect_stdout(io.StringIO()): + from PQAnalysis.cli.main import ( # pylint: disable=import-outside-toplevel + main, # noqa: F401 (imported for its side-effect free module) + ) + import PQAnalysis.cli.main as cli_main # pylint: disable=import-outside-toplevel + + commands = set() + + for attribute_name in dir(cli_main): + attribute = getattr(cli_main, attribute_name) + + if attribute_name.endswith("CLI") and hasattr( + attribute, "program_name"): + commands.add(attribute.program_name()) + + return commands + + +def _documented(env): + """ + Returns the per-document map of documented command names. + + Parameters + ---------- + env : sphinx.environment.BuildEnvironment + The active build environment. + + Returns + ------- + dict[str, list[str]] + Command names documented per docname. + """ + if not hasattr(env, "pq_cli_documented"): + env.pq_cli_documented = {} + + return env.pq_cli_documented + + +class PQCliTable(SphinxDirective): + """ + Renders a validated list-table of ``pqanalysis`` subcommands. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + option_spec = {"title": directives.unchanged} + + def run(self): + """ + Builds the list-table nodes from the directive content. + + Returns + ------- + list[docutils.nodes.Node] + The rendered table. + """ + registry = _registered_commands() + rows = [] + n_columns = 2 + + for line in self.content: + if not line.strip(): + continue + + parts = [part.strip() for part in line.split(_ROW_SEPARATOR)] + + if len(parts) not in (2, 3): + raise self.error( + "pq-cli-table rows must be 'name -- purpose' or " + f"'name -- purpose -- input', got: {line!r}" + ) + + name = parts[0] + + if name not in registry: + raise self.error( + f"pq-cli-table lists {name!r}, which is not a " + "registered pqanalysis command. Registered commands: " + f"{', '.join(sorted(registry))}" + ) + + _documented(self.env).setdefault( + self.env.docname, [] + ).append(name) + rows.append(parts) + n_columns = max(n_columns, len(parts)) + + title = self.options.get("title", "Commands") + widths = "24 50 26" if n_columns == 3 else "28 72" + headers = ["Command", "Purpose"] + + if n_columns == 3: + headers.append("Primary input") + + text = ViewList() + + def emit(line): + text.append(line, "pq-cli-table") + + emit(f".. list-table:: {title}") + emit(" :class: pq-command-table") + emit(" :header-rows: 1") + emit(f" :widths: {widths}") + emit("") + + emit(f" * - {headers[0]}") + + for header in headers[1:]: + emit(f" - {header}") + + for parts in rows: + name = parts[0] + padded = parts + [""] * (n_columns - len(parts)) + emit(f" * - :ref:`{name} `") + + for cell in padded[1:]: + emit(f" - {cell}") + + node = nodes.section() + node.document = self.state.document + self.state.nested_parse(text, self.content_offset, node) + + return node.children + + +class PQCliCovered(SphinxDirective): + """ + Marks commands as documented in prose instead of a table. + + The directive renders nothing; it only records its content so the + completeness check accepts commands such as ``convert`` that are + described in running text. + """ + + has_content = True + + def run(self): + """ + Records the covered command names. + + Returns + ------- + list + An empty node list. + """ + registry = _registered_commands() + + for line in self.content: + name = line.strip() + + if not name: + continue + + if name not in registry: + raise self.error( + f"pq-cli-covered lists {name!r}, which is not a " + "registered pqanalysis command." + ) + + _documented(self.env).setdefault( + self.env.docname, [] + ).append(name) + + return [] + + +def _purge(app, env, docname): # pylint: disable=unused-argument + """ + Drops the recorded commands of a document that is re-read. + """ + _documented(env).pop(docname, None) + + +def _merge(app, env, docnames, other): # pylint: disable=unused-argument + """ + Merges recorded commands from a parallel build worker. + """ + for docname, names in _documented(other).items(): + _documented(env).setdefault(docname, []).extend(names) + + +def _check(app, env): + """ + Verifies every registered command is documented exactly once. + """ + documented = [ + name for names in _documented(env).values() for name in names + ] + + if not documented: + return + + registry = _registered_commands() + missing = sorted(registry - set(documented)) + duplicated = sorted( + {name for name in documented if documented.count(name) > 1} + ) + + if missing: + logger.warning( + "pqanalysis commands missing from the command-line " + "reference: %s", + ", ".join(missing), + ) + + if duplicated: + logger.warning( + "pqanalysis commands documented more than once in the " + "command-line reference: %s", + ", ".join(duplicated), + ) + + +def setup(app): + """ + Registers the directives and consistency check. + + Parameters + ---------- + app : sphinx.application.Sphinx + The Sphinx application. + + Returns + ------- + dict + Extension metadata. + """ + app.add_directive("pq-cli-table", PQCliTable) + app.add_directive("pq-cli-covered", PQCliCovered) + app.connect("env-purge-doc", _purge) + app.connect("env-merge-info", _merge) + app.connect("env-check-consistency", _check) + + return { + "version": "1.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/source/conf.py b/docs/source/conf.py index 3047739e..e7417a72 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,6 +11,7 @@ sys.path.insert(0, str(PROJECT_ROOT)) sys.path.insert(0, str(SOURCE_DIR / "_plots")) +sys.path.insert(0, str(SOURCE_DIR / "_ext")) project = "PQAnalysis" author = "the PQAnalysis authors" @@ -35,6 +36,7 @@ "sphinx.ext.inheritance_diagram", "sphinx_sitemap", "matplotlib.sphinxext.plot_directive", + "pq_cli_tables", "myst_parser", "sphinx_copybutton", ] diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index 3d7d310c..d53e5876 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -9,35 +9,22 @@ subcommand also provides local help: $ pqanalysis --help $ pqanalysis rdf --help +The command tables on this page are validated against the command registry at +build time: a missing, renamed or undocumented command fails the +documentation build. + Analysis commands ----------------- -.. list-table:: Analysis commands - :class: pq-command-table - :header-rows: 1 - :widths: 24 50 26 - - * - Command - - Purpose - - Primary input - * - :ref:`rdf ` - - Radial distribution and cumulative coordination - - Input file - * - :ref:`msd ` - - Mean square displacement and diffusion fits - - Input file - * - :ref:`vacf ` - - Velocity or charge-flux correlation and spectra - - Input file - * - :ref:`vibrations ` - - Hessian normal modes and optional IR intensities - - Input file - * - :ref:`check_momentum ` - - Total linear momentum per velocity frame - - Trajectory files - * - :ref:`build_spectrum ` - - Gaussian or Lorentzian broadening of discrete lines - - Line table +.. pq-cli-table:: + :title: Analysis commands + + rdf -- Radial distribution and cumulative coordination -- Input file + msd -- Mean square displacement and diffusion fits -- Input file + vacf -- Velocity or charge-flux correlation and spectra -- Input file + vibrations -- Hessian normal modes and optional IR intensities -- Input file + check_momentum -- Total linear momentum per velocity frame -- Trajectory files + build_spectrum -- Gaussian or Lorentzian broadening of discrete lines -- Line table Analysis commands accept ``--export FILE`` where applicable. Repeat the option to produce several output formats without repeating the calculation. @@ -50,47 +37,33 @@ analysis tables and writes one or more target formats. It preserves complete schemas and hidden XVG data sets. See :doc:`the generated option reference <../code/PQAnalysis.cli.convert>`. +.. pq-cli-covered:: + + convert + Structure and trajectory conversion ----------------------------------- -.. list-table:: Structure and trajectory commands - :class: pq-command-table - :header-rows: 1 - :widths: 28 72 - - * - Command - - Purpose - * - :ref:`rst2xyz ` - - Convert a PQ restart structure to XYZ - * - :ref:`xyz2rst ` - - Convert XYZ coordinates to a PQ restart structure - * - :ref:`xyz2gen ` - - Convert XYZ to DFTB+ GEN - * - :ref:`gen2xyz ` - - Convert DFTB+ GEN to XYZ - * - :ref:`traj2box ` - - Extract periodic box data from trajectories - * - :ref:`traj2extxyz ` - - Write extended XYZ trajectories with selected metadata - * - :ref:`traj2qmcfc ` - - Convert trajectories to QMCFC conventions +.. pq-cli-table:: + :title: Structure and trajectory commands + + rst2xyz -- Convert a PQ restart structure to XYZ + xyz2rst -- Convert XYZ coordinates to a PQ restart structure + xyz2gen -- Convert XYZ to DFTB+ GEN + gen2xyz -- Convert DFTB+ GEN to XYZ + traj2box -- Extract periodic box data from trajectories + traj2extxyz -- Write extended XYZ trajectories with selected metadata + traj2qmcfc -- Convert trajectories to QMCFC conventions Simulation-support commands --------------------------- -.. list-table:: Simulation-support commands - :class: pq-command-table - :header-rows: 1 - :widths: 28 72 - - * - Command - - Purpose - * - :ref:`continue_input ` - - Continue indexed PQ or QMCFC input/output sequences - * - :ref:`add_molecules ` - - Add molecular structures to an existing system - * - :ref:`build_nep_traj ` - - Build Neuroevolution Potential (NEP) training and test trajectories +.. pq-cli-table:: + :title: Simulation-support commands + + continue_input -- Continue indexed PQ or QMCFC input/output sequences + add_molecules -- Add molecular structures to an existing system + build_nep_traj -- Build Neuroevolution Potential (NEP) training and test trajectories Commands refuse unsafe output replacement by default. Consult each generated reference page for its supported writing modes and format-specific options. From cfd97cf10bec5bc2fabcbcb2726cda3cad62e9ca Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:25:59 +0200 Subject: [PATCH 10/12] fix: read the cli registry without importing the dispatcher The command-table extension scraped the attributes of the dispatcher module. During the documentation build the api-doc generator imports the package at the same time, so the dispatcher could be observed half-initialized and the extension then saw no commands at all and rejected every documented one. The strict build failed on CI while passing locally, because the outcome depended on import order. Read the dispatch table from the module source with ast instead and import only the individual command modules, which have no import cycle with the dispatcher. Raise immediately if the table cannot be read, so an unreadable registry can no longer look like an empty one. --- docs/source/_ext/pq_cli_tables.py | 67 +++++++++++++++++++++++++------ 1 file changed, 55 insertions(+), 12 deletions(-) diff --git a/docs/source/_ext/pq_cli_tables.py b/docs/source/_ext/pq_cli_tables.py index 9391a05a..2bd44be8 100644 --- a/docs/source/_ext/pq_cli_tables.py +++ b/docs/source/_ext/pq_cli_tables.py @@ -17,9 +17,16 @@ while the command name and its cross reference come from the code. """ +import ast import contextlib +import functools +import importlib import io +from pathlib import Path + +import PQAnalysis.cli as cli_module + from docutils import nodes from docutils.parsers.rst import directives from docutils.statemachine import ViewList @@ -31,32 +38,68 @@ _ROW_SEPARATOR = " -- " +@functools.lru_cache(maxsize=1) def _registered_commands(): """ Returns the registered command names from the PQAnalysis CLI. - The import prints the PQAnalysis header to stdout, which is - swallowed so that it does not clutter the Sphinx build output. + The dispatcher module is read with :py:mod:`ast` instead of being + imported: during the documentation build the api-doc generator + imports the package itself, so importing the dispatcher here can + observe a partially initialized module whose class attributes do + not exist yet. The class names of the dispatch table and their + defining modules are therefore taken from the source, and only the + individual command modules are imported to read their program + names. Importing a command module prints the PQAnalysis header to + stdout, which is swallowed so that it does not clutter the build + output. Returns ------- set[str] The names of all registered ``pqanalysis`` subcommands. + + Raises + ------ + RuntimeError + If no command could be read from the dispatcher module. """ - with contextlib.redirect_stdout(io.StringIO()): - from PQAnalysis.cli.main import ( # pylint: disable=import-outside-toplevel - main, # noqa: F401 (imported for its side-effect free module) - ) - import PQAnalysis.cli.main as cli_main # pylint: disable=import-outside-toplevel + main_source = Path(cli_module.__file__).with_name("main.py") + tree = ast.parse(main_source.read_text(encoding="utf-8")) + + modules_of_class = {} + dispatched_classes = set() + + for node in ast.walk(tree): + # 'from .rdf import RDFCLI' -> {'RDFCLI': 'rdf'} + if isinstance(node, ast.ImportFrom) and node.module: + for alias in node.names: + modules_of_class[alias.asname or alias.name] = node.module + + # 'RDFCLI.program_name(): RDFCLI' inside the dispatch table + if isinstance(node, ast.Attribute) and node.attr == "program_name": + if isinstance(node.value, ast.Name): + dispatched_classes.add(node.value.id) commands = set() - for attribute_name in dir(cli_main): - attribute = getattr(cli_main, attribute_name) + with contextlib.redirect_stdout(io.StringIO()): + for class_name in dispatched_classes: + module_name = modules_of_class.get(class_name) + + if module_name is None: + continue + + module = importlib.import_module( + f"{cli_module.__name__}.{module_name}" + ) + commands.add(getattr(module, class_name).program_name()) - if attribute_name.endswith("CLI") and hasattr( - attribute, "program_name"): - commands.add(attribute.program_name()) + if not commands: + raise RuntimeError( + "the pq-cli-table extension could not read any command from " + f"{main_source}; the dispatch table format may have changed" + ) return commands From a882b414e8832e2f6603e104fcabae0dc4232fe2 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:31:52 +0200 Subject: [PATCH 11/12] fix: read the command names from the dispatch table The dispatcher now keeps a lazy table that maps every command name to its module, class and description, so the command tables of the reference can be validated by reading that table alone. Parse it from the module source and drop the import of the individual command modules: the extension no longer depends on import order or on the package being importable at all, and a table it cannot read is reported instead of silently looking empty. --- docs/source/_ext/pq_cli_tables.py | 67 +++++++++++++------------------ 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/docs/source/_ext/pq_cli_tables.py b/docs/source/_ext/pq_cli_tables.py index 2bd44be8..17d0fe85 100644 --- a/docs/source/_ext/pq_cli_tables.py +++ b/docs/source/_ext/pq_cli_tables.py @@ -3,8 +3,8 @@ with the code. The ``pq-cli-table`` directive renders a list-table of commands. Every -command name in the table body is validated against the registry in -:py:mod:`PQAnalysis.cli.main` at build time, so a renamed or removed +command name in the table body is validated against the dispatch +table of :py:mod:`PQAnalysis.cli.main` at build time, so a renamed or removed command fails the documentation build instead of leaving a stale table row. The ``pq-cli-covered`` directive marks commands that are documented in prose instead of a table. After the build has read every page, the @@ -18,10 +18,7 @@ """ import ast -import contextlib import functools -import importlib -import io from pathlib import Path @@ -37,22 +34,20 @@ _ROW_SEPARATOR = " -- " +#: the name of the dispatch table in PQAnalysis.cli.main +_REGISTRY_NAME = "_COMMANDS" + @functools.lru_cache(maxsize=1) def _registered_commands(): """ Returns the registered command names from the PQAnalysis CLI. - The dispatcher module is read with :py:mod:`ast` instead of being - imported: during the documentation build the api-doc generator - imports the package itself, so importing the dispatcher here can - observe a partially initialized module whose class attributes do - not exist yet. The class names of the dispatch table and their - defining modules are therefore taken from the source, and only the - individual command modules are imported to read their program - names. Importing a command module prints the PQAnalysis header to - stdout, which is swallowed so that it does not clutter the build - output. + The dispatch table is read from the source of the dispatcher module + with :py:mod:`ast` instead of importing it. During the documentation + build the api-doc generator imports the package itself, so an import + here can observe a partially initialized module; reading the source + is independent of import order and needs no import at all. Returns ------- @@ -62,43 +57,37 @@ def _registered_commands(): Raises ------ RuntimeError - If no command could be read from the dispatcher module. + If the dispatch table could not be read from the dispatcher. """ main_source = Path(cli_module.__file__).with_name("main.py") tree = ast.parse(main_source.read_text(encoding="utf-8")) - modules_of_class = {} - dispatched_classes = set() + commands = set() for node in ast.walk(tree): - # 'from .rdf import RDFCLI' -> {'RDFCLI': 'rdf'} - if isinstance(node, ast.ImportFrom) and node.module: - for alias in node.names: - modules_of_class[alias.asname or alias.name] = node.module + if not isinstance(node, ast.Assign): + continue - # 'RDFCLI.program_name(): RDFCLI' inside the dispatch table - if isinstance(node, ast.Attribute) and node.attr == "program_name": - if isinstance(node.value, ast.Name): - dispatched_classes.add(node.value.id) + targets = { + target.id + for target in node.targets if isinstance(target, ast.Name) + } - commands = set() + if _REGISTRY_NAME not in targets: + continue - with contextlib.redirect_stdout(io.StringIO()): - for class_name in dispatched_classes: - module_name = modules_of_class.get(class_name) - - if module_name is None: - continue + if not isinstance(node.value, ast.Dict): + continue - module = importlib.import_module( - f"{cli_module.__name__}.{module_name}" - ) - commands.add(getattr(module, class_name).program_name()) + for key in node.value.keys: + if isinstance(key, ast.Constant) and isinstance(key.value, str): + commands.add(key.value) if not commands: raise RuntimeError( - "the pq-cli-table extension could not read any command from " - f"{main_source}; the dispatch table format may have changed" + f"the pq-cli-table extension could not read {_REGISTRY_NAME} " + f"from {main_source}; the dispatch table format may have " + "changed and the command tables can no longer be validated" ) return commands From 289a3f40830ae2370f758643b1644b6dece16ad3 Mon Sep 17 00:00:00 2001 From: "Josef M. Gallmetzer" <64498081+galjos@users.noreply.github.com> Date: Fri, 21 Aug 2026 13:17:42 +0200 Subject: [PATCH 12/12] docs: document the physics, its sources and its limits The analysis pages described what the software computes but not where the methods come from or when their results can be trusted. - add a references page with the primary sources for every implemented estimator, and cite them from the analysis pages where the quantity is defined; state that the project has no citable DOI of its own yet - give the vibrational analysis its mathematics: the mass-weighted Hessian and its eigenproblem, the wavenumber conversion with its unit chain, the automatic sign heuristic, force constants, reduced masses and infrared intensities, each matching the implementation - describe the linear momentum as a drift diagnostic and state the precision floor below which a reported norm is parsing noise - add validity and interpretation sections to the radial distribution, mean square displacement and velocity autocorrelation pages: the minimum-image limit on r_max, the diffusive regime and fit window, the frequency resolution and Nyquist limit, and that no finite-size correction of the diffusion coefficient is applied --- docs/source/analyses/momentum.rst | 128 ++++++++-- docs/source/analyses/msd.rst | 209 +++++++++++++++- docs/source/analyses/rdf.rst | 163 +++++++++++- docs/source/analyses/vacf.rst | 230 +++++++++++++++-- docs/source/analyses/vibrations.rst | 373 ++++++++++++++++++++++++++-- docs/source/index.rst | 1 + docs/source/references.rst | 138 ++++++++++ 7 files changed, 1173 insertions(+), 69 deletions(-) create mode 100644 docs/source/references.rst diff --git a/docs/source/analyses/momentum.rst b/docs/source/analyses/momentum.rst index 06114948..9bb3e639 100644 --- a/docs/source/analyses/momentum.rst +++ b/docs/source/analyses/momentum.rst @@ -1,16 +1,35 @@ Total Linear Momentum ===================== -For every velocity frame, PQAnalysis evaluates the selected atoms' total -linear momentum, +For every velocity frame, PQAnalysis evaluates the total linear momentum of the +selected atoms, .. math:: - \mathbf{P}(t) = \sum_i m_i\mathbf{v}_i(t), + \mathbf{P}(t) = \sum_i m_i\mathbf{v}_i(t) , -and writes its scaled norm. This is a diagnostic for center-of-mass drift and -momentum conservation, not a substitute for inspecting the thermostat, -constraints or integration scheme. +and writes its scaled norm + +.. math:: + + p(t) = \sigma\,\lVert\mathbf{P}(t)\rVert + = \sigma\left\lVert\sum_i m_i\mathbf{v}_i(t)\right\rVert , + +one value per frame. Here :math:`m_i` is the atomic mass in amu taken from the +topology, :math:`\mathbf{v}_i` is the atomic velocity read from the trajectory, +and :math:`\sigma` is the ``scale`` factor. This is a diagnostic for +center-of-mass drift and momentum conservation [Allen2017]_, not a substitute +for inspecting the thermostat, constraints or integration scheme. + +Units +----- + +PQ velocity trajectories store velocities in Å·s⁻¹, so :math:`\mathbf{P}` is in +amu·Å·s⁻¹. The default :math:`\sigma = 10^{-15}` converts that to +amu·Å·fs⁻¹, the unit of the second output column. Any other value of +``--scale`` simply multiplies the norm, and it is then the user's +responsibility to make :math:`\sigma` match the velocity convention of the +input trajectory. Run the diagnostic ------------------ @@ -21,23 +40,96 @@ Run the diagnostic --selection all \ --output momentum.dat -The default scale of ``1e-15`` converts PQ velocity-trajectory values from -amu·Å·s⁻¹ to amu·Å·fs⁻¹. Use ``--scale`` when the input convention differs. +The output contains a one-based frame index and the scaled momentum norm. Use +``--scale`` when the input convention differs from Å·s⁻¹, and ``--selection`` +to restrict the sum to a subset of atoms. -Interpretation --------------- +Precision and the noise floor +----------------------------- + +:math:`\mathbf{P}` is a heavily cancelling sum. In a well-behaved simulation +the individual terms :math:`m_i\mathbf{v}_i` are large and nearly cancel, so +the surviving norm is smaller than any single term by many orders of magnitude. +The smallest norm that still carries information is therefore set by the +relative precision :math:`\varepsilon` of the velocity values, not by the +accumulator, which is always float64: + +.. math:: + + \lVert\mathbf{P}\rVert \gtrsim + \varepsilon\sum_i m_i\lVert\mathbf{v}_i\rVert . + +Two code paths set :math:`\varepsilon` differently: -The output contains a one-based frame index and the scaled momentum norm. A -systematic increase can indicate center-of-mass drift. Oscillatory or noisy -behavior must be interpreted relative to the total mass, velocity scale and -numerical precision. +* File-backed PQ and QMCFC velocity trajectories — files recognized as ``.vel`` + or ``.velocs`` and read through ``check_momentum`` — are parsed directly as + float64. Here :math:`\varepsilon` is the precision of the text itself, that + is, the number of significant digits the MD engine wrote. +* Other xyz-family trajectory formats read from file keep the single-precision + arrays produced by the general frame reader, giving + :math:`\varepsilon\approx 1.2\times10^{-7}` before the values are widened to + float64 for the sum. +* Trajectory objects built in memory keep the precision of the velocity arrays + they were given, so a float64 array is summed without any loss. + +As a rule of thumb, a scaled norm below roughly :math:`10^{-7}` of +:math:`\sum_i m_i\lVert\mathbf{v}_i\rVert` is parsing and round-off noise +rather than physical drift. Compare against that scale before reading anything +into an absolute value. -File-backed PQ and QMCFC velocity trajectories are parsed directly as float64. The compatibility path multiplies and sums atoms in the same order as the -legacy ``equipartition.jl`` calculation. Native output uses 17 significant -digits, so reloading it as float64 preserves each calculated value exactly. -Trajectory objects use the numerical precision already stored in the object. +legacy ``equipartition.jl`` calculation [thhTools]_, so residuals near the +float64 noise floor are reproduced bit for bit. Native output uses 17 +significant digits, so reloading it as float64 preserves each calculated value +exactly. + +Validity and interpretation +--------------------------- + +A trustworthy result is a flat trace: :math:`p(t)` fluctuating around the noise +floor with no trend over the whole trajectory. The shape of the series carries +the information, not any single value. + +* **A systematic increase** indicates center-of-mass drift — the classic + signature of an integration time step that is too large, of accumulated + round-off, or of a thermostat that adds momentum without removing it. +* **A step** at one frame usually marks a restart, a velocity reassignment or a + change of ensemble rather than a physical process. +* **A flat trace at a large value** means the simulation started with non-zero + total momentum. It is conserved, but the center of mass is translating, and + MSD or diffusion coefficients from that trajectory are biased unless the + drift is removed. + +The diagnostic does not apply, or must be read differently, in these cases: + +* **Partial selections.** Momentum conservation is a statement about the whole + system. The momentum of a subset of atoms obeys no conservation law and + fluctuates by construction, so ``--selection`` is useful for locating which + species carries a drift, not for testing conservation. +* **Systems with external forces.** Walls, position restraints, frozen atoms, + external fields and momentum-removing thermostats break translational + invariance on purpose. A non-conserved momentum is then the expected result. +* **Unknown masses.** Every selected atom must have a known mass; the analysis + refuses to run otherwise, because a missing mass would silently change the + sum. +* **Equipartition and temperature.** This is a single vector sum over the + system. It says nothing about how kinetic energy is distributed over degrees + of freedom, and a conserved total momentum is no evidence of a correct + temperature or of proper thermostatting. + +Output and API +-------------- See :ref:`analysis-output-momentum` for the output schema. Python workflows can call :func:`PQAnalysis.analysis.momentum.api.check_momentum` or use :class:`PQAnalysis.analysis.momentum.momentum.Momentum` directly. + +References +---------- + +* [Allen2017]_ describes conserved quantities in a molecular-dynamics run and + the removal of center-of-mass motion. +* [thhTools]_ is the legacy program whose summation order the compatibility + path reproduces. + +Full entries are listed in :doc:`../references`. diff --git a/docs/source/analyses/msd.rst b/docs/source/analyses/msd.rst index 5ad28d31..3135f493 100644 --- a/docs/source/analyses/msd.rst +++ b/docs/source/analyses/msd.rst @@ -1,9 +1,9 @@ Mean Square Displacement ======================== -The mean square displacement measures translational motion over a lag time. -For Cartesian component :math:`\alpha`, PQAnalysis evaluates multiple time -origins according to +The mean square displacement measures translational motion over a lag time +[Allen2017]_. For Cartesian component :math:`\alpha`, PQAnalysis averages over +multiple time origins [Rahman1964]_ according to .. math:: @@ -46,25 +46,199 @@ in ps and enables diffusion fitting; ``fit_window`` selects the trailing points used by that fit. File-backed orthorhombic trajectories use a bounded compatibility path that -preserves the Diffcalc operation order. Unsupported cells or inputs return to -the general streaming implementation. +preserves the operation order of the legacy ``Diffcalc`` program [thhTools]_. +Unsupported cells or inputs return to the general streaming implementation. Interpretation -------------- The output contains the lag index and the x, y and z components in Ų. Their sum is the total three-dimensional MSD. In an -isotropic diffusive regime, +isotropic diffusive regime, the Einstein relation [Einstein1905]_ links the +long-time slope to the self-diffusion coefficient, .. math:: D = \frac{1}{6}\frac{d}{dt}\mathrm{MSD}_{\mathrm{total}}(t). PQAnalysis also fits each Cartesian component with the corresponding -one-dimensional factor. The resulting coefficients, uncertainties and -:math:`R^2` values are written to the log file in m²·s⁻¹. A fit is -physically meaningful only over a linear diffusive interval; short-time -ballistic motion and poorly sampled long lags should not be included blindly. +one-dimensional factor, :math:`D_\alpha = \tfrac{1}{2}\,\mathrm{d} +\mathrm{MSD}_{\alpha}/\mathrm{d}t`. The resulting coefficients, uncertainties +and :math:`R^2` values are written to the log file in m²·s⁻¹, converted from +Ų·ps⁻¹ with a factor of :math:`10^{-8}`. + +Validity and interpretation +--------------------------- + +Confirm the diffusive regime before trusting a fit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Einstein relation applies only where the MSD is linear in time. The +diagnostic is the local log-log slope + +.. math:: + + \beta(t) = \frac{\mathrm{d}\log\mathrm{MSD}_{\mathrm{total}}(t)} + {\mathrm{d}\log t}, + +which equals 2 in the ballistic short-time regime, can sit well below 1 on a +sub-diffusive plateau in cage-forming liquids, glasses and confined systems, +and approaches 1 only once the motion has become diffusive. Fit only over an +interval where :math:`\beta \approx 1`, and quote that interval together with +:math:`D`. + +PQAnalysis does not compute :math:`\beta` and performs no linearity test. The +diagnostic has to be evaluated from ``out_file``: multiply column 1 by +``time_step`` to obtain the lag time, and sum columns 2 through 4 to obtain +:math:`\mathrm{MSD}_{\mathrm{total}}`. + +.. warning:: + + A high :math:`R^2` is not evidence of diffusion. A purely ballistic + :math:`\mathrm{MSD}\propto t^2` fitted over the trailing points of a window + still yields :math:`R^2 \approx 0.999` and a finite, entirely meaningless + :math:`D`. The :math:`R^2` in the log file measures how straight the + selected points are, not whether they belong to a diffusive regime. + +Choosing the fit window +^^^^^^^^^^^^^^^^^^^^^^^ + +``fit_window`` is the number of *trailing* MSD points used by the fit, so the +fit always ends at the largest lag. With :math:`W` for ``window``, :math:`F` +for ``fit_window`` and :math:`\Delta t` for ``time_step``, the fitted lag range +is + +.. math:: + + \left[(W - F + 1)\,\Delta t,\; W\,\Delta t\right]. + +The default is +``max(2, window // 5)``, the last 20 % of the window. Because the fit is +anchored at the end, two consequences follow: + +* The ballistic short-time region is excluded by making ``fit_window`` + *smaller*, which moves the start of the fit to later lag times. +* The noisy long-lag tail cannot be excluded through ``fit_window`` at all; it + is always inside the fit. To move the fit away from the tail, reduce + ``window`` so that the largest lag is itself still well sampled. + +How much averaging the curve actually carries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Time origins spawn every ``gap`` frames up to +``stop_frame = (n_frames - window) // gap * gap``, so their number is + +.. math:: + + N_{\mathrm{origins}} = \left\lfloor + \frac{N_{\mathrm{frames}} - W}{G}\right\rfloor, + +for ``window`` :math:`= W` and ``gap`` :math:`= G`. It is printed as +``Number of origins`` in the log file. Every origin covers the full +window, so in this implementation *every* lag bin from 0 to ``window`` is +averaged over exactly this many origins. The origin count does not decay with +lag, as it does in estimators that use every frame as a time origin. + +That does not make the tail reliable. The origins overlap heavily, and at lag +:math:`\tau` a trajectory of total length :math:`T` contains at most +:math:`T/\tau` statistically independent displacement windows. The effective +sample size still falls as :math:`1/\tau`, which is why the long-lag tail +remains the noisiest part of the curve even though its nominal origin count is +unchanged. + +The same expression sets the trajectory length you need. Choosing ``window`` +close to the trajectory length starves the entire curve, not only its tail: +1100 frames with ``window = 1000`` and ``gap = 10`` leave 10 origins for every +lag. A defensible :math:`D` requires a trajectory much longer than the longest +fitted lag — that lag must already lie beyond the velocity correlation time so +that the motion is diffusive, and the trajectory must then be long enough to +contain many independent windows of that length. + +What the reported uncertainty is, and is not +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``+/-`` value in the log file is the standard error of the fitted slope +returned by ``scipy.stats.linregress``, scaled by the same +:math:`10^{-8}/(2d)` factor as the coefficient itself, with :math:`d = 1` for +the Cartesian components and :math:`d = 3` for the total. It is the statistical +error of a straight-line fit, computed as if the fitted MSD points were +independent samples. + +They are not. Neighbouring lag bins share time origins and atoms and are +strongly correlated, so the quoted error systematically understates the true +uncertainty. PQAnalysis performs no block averaging, no averaging over +independent trajectories and no correction for the correlation between lags. +Treat the printed uncertainty as a lower bound, and obtain a realistic error +bar from independent runs — or at least from the spread of :math:`D` under +variation of the fit window and between the three Cartesian components. + +Finite-size effects on D +^^^^^^^^^^^^^^^^^^^^^^^^ + +Self-diffusion coefficients computed under periodic boundary conditions are +systematically too small, because the periodic images suppress hydrodynamic +backflow. The leading correction for a cubic box is + +.. math:: + + D_0 = D_{\mathrm{PBC}} + \frac{\xi\,k_{\mathrm{B}} T}{6\pi\eta L}, + \qquad \xi = 2.837297, + +with shear viscosity :math:`\eta` and box length :math:`L`. + +.. important:: + + PQAnalysis does **not** apply the Yeh-Hummer correction, or any other + finite-size correction. The value written to the log file is the raw + periodic :math:`D_{\mathrm{PBC}}` at the simulated box size, and no + viscosity enters the code anywhere. Apply the correction externally, or + extrapolate :math:`D` to :math:`1/L \to 0` across several box sizes. + + Yeh, I.-C.; Hummer, G. System-Size Dependence of Diffusion Coefficients and + Viscosities from Molecular Dynamics Simulations with Periodic Boundary + Conditions. *The Journal of Physical Chemistry B* **2004**, *108* (40), + 15873-15879. `doi:10.1021/jp0477147 + `__ + +Coordinates and periodic images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Displacements must be free of periodic jumps, and PQAnalysis handles this +itself: each per-frame displacement is folded into the minimum image of the +current cell and accumulated into a running shift, so a trajectory written with +coordinates wrapped into the box yields exactly the same MSD as the +corresponding unwrapped trajectory. No pre-unwrapping step is required. + +The scheme is exact only while no selected atom travels further than half the +shortest box vector between two *written* frames. A sparse output stride breaks +that condition silently: the misassigned images truncate every affected +displacement to at most half a box vector, which biases the MSD and therefore +:math:`D` downwards with no warning. For a vacuum cell no unwrapping is applied +and the coordinates are used as they are. + +Two normalization traps +^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + ``n_start`` shrinks the MSD. Frames before ``n_start`` are read so that the + unwrapping stays continuous, but they spawn no time origins — while the + divisor keeps its legacy value ``stop_frame // gap``, which still counts + them. The whole curve, and therefore :math:`D`, is scaled by the ratio of + origins that actually spawned to that divisor. With 60 frames, + ``window = 20`` and ``gap = 5``, ``n_start = 20`` leaves 5 of 8 counted + origins and returns 62.5 % of the correct MSD. This legacy Diffcalc + convention is deliberate. To start later without the bias, truncate the + trajectory file instead, or rescale the result yourself. + +.. warning:: + + A trajectory of exactly ``window`` frames with ``gap = 1`` takes the legacy + single-origin branch: one origin spawns, and the final lag bin + (``lag = window``) can never be sampled and is written as exactly 0.0. A + warning is emitted when the analysis is set up. Since the fit always uses trailing points, + that zero is inside any requested diffusion fit and corrupts it. Use a + longer trajectory or a smaller ``window``. Output and API -------------- @@ -73,3 +247,18 @@ See :ref:`analysis-output-msd` for the exact table layout. The input-file entry point is :func:`PQAnalysis.analysis.msd.api.msd`; direct workflows can use :class:`PQAnalysis.analysis.msd.msd.MSD` and inspect its total MSD and fit results. + +References +---------- + +* [Einstein1905]_ derives the linear growth of the mean square displacement + that the diffusion fit assumes. +* [Rahman1964]_ is the first molecular-dynamics measurement of single-particle + displacements and velocity correlations in a liquid. +* [Allen2017]_ and [Frenkel2002]_ cover the multiple-time-origin estimator, + coordinate unwrapping in a periodic cell and the practical limits of + extracting :math:`D` from a finite trajectory. +* [thhTools]_ is the legacy program whose operation order the compatibility + path reproduces. + +Full entries are listed in :doc:`../references`. diff --git a/docs/source/analyses/rdf.rst b/docs/source/analyses/rdf.rst index bc09e9fe..bfa1fa4f 100644 --- a/docs/source/analyses/rdf.rst +++ b/docs/source/analyses/rdf.rst @@ -3,8 +3,8 @@ Radial Distribution Function The radial distribution function measures the probability of finding a target atom at distance :math:`r` from a reference atom relative to an ideal gas at -the same effective target density. For histogram bin :math:`i`, PQAnalysis -uses +the same effective target density [Hansen2013]_. For histogram bin :math:`i`, +PQAnalysis uses the standard simulation estimator [Allen2017]_, .. math:: @@ -50,7 +50,8 @@ Legacy-compatible arithmetic For a file-backed periodic orthorhombic trajectory, specifying ``delta_r`` alone with the default ``r_min = 0`` selects the legacy-compatible RDF path. Coordinates are parsed as float64; histogram binning and all five output -columns preserve the corrected legacy C operation order. Explicit ``r_max`` or +columns preserve the corrected operation order of the legacy ``RDF`` C code +[thhTools]_. Explicit ``r_max`` or ``n_bins``, triclinic or vacuum cells, and intramolecular exclusion use the general PQAnalysis path. The minimal example above sets ``r_max`` explicitly and therefore uses the general path. @@ -66,8 +67,147 @@ Interpretation * Self pairs are excluded. Intramolecular pairs are included unless molecular topology is supplied and explicitly excluded. -Normalization, finite-size effects, selection definitions and trajectory -sampling should be considered before comparing RDFs from different systems. +Validity and interpretation +--------------------------- + +r_max and the minimum-image limit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Distances are evaluated under the minimum-image convention, which is only +meaningful while the sphere of radius :math:`r` fits inside the periodic cell. +Beyond that radius the shell is no longer fully covered by nearest images, the +pair count falls short of the ideal-gas expectation used for normalization, and +:math:`g(r)` is biased low for purely geometric reasons. The hard limit is half +the shortest perpendicular width of the cell, which for an orthorhombic box is +half the shortest box vector, + +.. math:: + + r_{\max} \le \tfrac{1}{2}\min(a, b, c). + +PQAnalysis enforces this on the general path: a requested ``r_max`` — whether +given directly, or implied by ``n_bins`` and ``delta_r`` — that exceeds +:math:`\tfrac{1}{2}\min(a,b,c)` is clamped down to it, with a warning in the +log. The bound is taken over *all* frames, so for a variable cell the smallest +box in the whole trajectory sets the limit. If a run covers a shorter range +than requested, this clamp is why. + +.. warning:: + + Two cases escape the bound and must be checked by hand. + + **Non-cubic boxes on the legacy path.** With ``delta_r`` alone on a periodic + orthorhombic trajectory, the bin count is derived from *half the longest* + box vector, while the legacy kernel discards every pair beyond half the + *shortest* one. A 10 × 14 × 30 Å box with ``delta_r = 0.1`` therefore + produces bins out to 14.9 Å, of which everything past 5.0 Å is exactly + zero — an artifact, not a depletion zone. Ignore all bins beyond + :math:`\tfrac{1}{2}\min(a,b,c)`, or set ``r_max`` explicitly to take the + general path. + + **Triclinic cells.** The bound uses box-vector lengths, not the + perpendicular widths of the cell, and for a skewed cell the inscribed sphere + is smaller than half the shortest vector. For :math:`a=b=c=10` Å with + :math:`\gamma = 60^\circ`, the clamp allows :math:`r_{\max} = 5.0` Å while + the true limit is 4.33 Å; an ideal gas in that cell already shows + :math:`g(r) \approx 0.92` between 4.33 and 4.7 Å and :math:`0.79` between + 4.7 and 5.0 Å. On triclinic cells, set ``r_max`` to half the smallest + perpendicular width yourself. + +Sampling: how smooth is smooth enough +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:math:`H_i` is a raw integer pair count, so a bin carries a relative counting +noise of roughly :math:`1/\sqrt{H_i}`. Reaching 1 % noise in a bin needs about +:math:`10^4` counts in that bin. The expected count grows with the shell +volume, + +.. math:: + + \langle H_i\rangle = \rho_T N_R N_F \Delta V_i \propto r_i^2\,\Delta r, + +so the small-:math:`r` bins are always the poorest and a first peak looks +ragged long before the plateau does. The three levers are the number of frames +:math:`N_F`, the size of the reference and target selections, and ``delta_r``: +halving ``delta_r`` halves the counts per bin and raises the relative noise by +:math:`\sqrt{2}`. Choose +``delta_r`` fine enough to locate the first peak and the first minimum — 0.02 +to 0.05 Å is typical — and then buy the smoothness back with frames, not by +widening bins. Curves that still wobble around 1 in the plateau region are not +converged, whatever the first peak looks like. + +Coordination numbers and the first minimum +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first minimum of :math:`g(r)` is the conventional boundary of the first +coordination shell: it is where the shell population is lowest, so the +coordination number is least sensitive to exactly where the cut is placed. +Column 3 of the output is the running coordination number + +.. math:: + + N(r_i) = \frac{1}{N_R N_F}\sum_{j \le i} H_j, + +the mean number of eligible target atoms per reference atom. Read it off at the +row whose :math:`g` is minimal. Two details matter when quoting the number: + +* Column 1 is the bin *center* while :math:`N(r_i)` accumulates through the + *upper* edge of that bin, so the quoted radius and the integration limit + differ by :math:`\Delta r / 2`. +* A shallow or ill-defined minimum means the coordination number is not + well-defined either. Quote the cutoff radius alongside the number, and check + how much it changes when the cutoff moves by one bin. + +Density normalization uses the average box volume +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The target density is :math:`\rho_T = N_T / \langle V\rangle`, where +:math:`\langle V\rangle` is the arithmetic mean of the per-frame cell volumes +over the whole trajectory. One density is used for all frames and all bins. + +For NVT, NVE and any other fixed-cell trajectory this is exact. For NPT it is +not: the correct normalization would divide each frame by its own volume, and +using a single mean instead scales the whole curve by +:math:`\langle V\rangle\langle 1/V\rangle`, which is greater than one whenever +the volume fluctuates. + +.. important:: + + The bias is uniform in :math:`r`, so it moves the plateau away from 1 + without changing peak positions. A deliberately extreme test — an ideal gas + in a trajectory alternating between 1000 ų and 2197 ų — returns + :math:`g(r) \approx 1.16` where the exact answer is 1.00, matching + :math:`\langle V\rangle\langle 1/V\rangle = 1.163`. + + Ordinary NPT volume fluctuations are far smaller and the effect is usually + negligible, but it is worth checking: the plateau of :math:`g(r)` at large + :math:`r` should sit at 1. If it does not, and the sampling is converged, + the volume distribution is the first thing to look at. Note also that + ``r_max`` is bounded by the *smallest* box in the trajectory, so a + fluctuating cell shortens the usable range. + +Selections, exclusions and comparability +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Self pairs are always excluded. Intramolecular pairs are *included* by default, +which for a molecular liquid puts intramolecular bond and angle distances into +the first bins of the histogram; they are real distances, but they are not the +intermolecular structure most RDFs are meant to show. Set +``no_intra_molecular = True``, with the topology files it requires, to remove +them. + +.. note:: + + With ``no_intra_molecular = True`` the effective target density is derived + from the exclusion list of the *first* reference atom only. The + normalization is therefore correct as long as every reference atom excludes + the same number of target atoms, which holds for a single molecular species + and fails for a reference selection spanning molecules of different sizes. + +Because :math:`g(r)` is normalized to an effective density defined by the +selections and the average volume, two RDFs are only comparable when the +selections, the exclusion setting, the thermodynamic state and the sampled +:math:`r` range all match. State them with the curve. Output and API -------------- @@ -79,3 +219,16 @@ normalization. The main Python entry point is The complete input-key table is documented with :class:`PQAnalysis.analysis.rdf.rdf_input_file_reader.RDFInputFileReader`. + +References +---------- + +* [Hansen2013]_ defines :math:`g(r)` in classical liquid-state theory and + relates it to the structure factor and to thermodynamic averages. +* [Allen2017]_ and [Frenkel2002]_ give the histogram estimator, its + spherical-shell normalization and the finite-size caveats that apply to a + periodic simulation cell. +* [thhTools]_ is the legacy program whose operation order the + legacy-compatible path reproduces. + +Full entries are listed in :doc:`../references`. diff --git a/docs/source/analyses/vacf.rst b/docs/source/analyses/vacf.rst index 8f8d5cd4..1a58c20c 100644 --- a/docs/source/analyses/vacf.rst +++ b/docs/source/analyses/vacf.rst @@ -2,7 +2,7 @@ VACF and Spectra ================ The normalized velocity autocorrelation function describes how rapidly atomic -velocities lose memory of their initial direction: +velocities lose memory of their initial direction [Rahman1964]_, [Allen2017]_: .. math:: @@ -13,18 +13,22 @@ velocities lose memory of their initial direction: \right\rangle_{t_0}. The brackets denote an average over admissible time origins, and the sum runs -over the selected atoms. This is the default, legacy-compatible estimator and -gives :math:`C_{vv}(0)=1`. The ``fft`` estimator instead averages the numerator -and denominator separately over all available origins before normalization. +over the selected atoms. This is the default, legacy-compatible estimator +[thhTools]_ and gives :math:`C_{vv}(0)=1`. The ``fft`` estimator instead +averages the numerator and denominator separately over all available origins +before normalization, evaluating the correlation through the power spectrum as +the Wiener-Khinchin theorem allows [Wiener1930]_, [Khintchine1934]_. -PQAnalysis can transform the correlation to a wavenumber-domain spectrum. If -static or time-dependent partial charges are supplied, it correlates -:math:`q_i\mathbf{v}_i` instead, producing a charge-flux spectrum that -approximates an infrared spectrum. +PQAnalysis can transform the correlation to a wavenumber-domain spectrum. That +transform of the velocity autocorrelation function is the vibrational density +of states [Dickey1969]_, [Thomas2013]_. If static or time-dependent partial +charges are supplied, it correlates :math:`q_i\mathbf{v}_i` instead, producing +a charge-flux spectrum that approximates an infrared spectrum [Thomas2013]_. The correlation written to ``out_file`` is not apodized. When a spectrum is requested, ``window_function`` multiplies a copy of the correlation before the -cosine transform. The optional ``windowed_out_file`` records that copy. +cosine transform [Harris1978]_. The optional ``windowed_out_file`` records that +copy. Correlation and spectrum ------------------------ @@ -73,14 +77,185 @@ Interpretation * A rapidly decaying VACF indicates fast velocity decorrelation. * In liquids, negative regions often indicate backscattering or cage motion; in solids, sign oscillations reflect bound vibrational motion. -* The sampling interval sets the Nyquist limit, and the correlation length sets - the resolving power. Zero-padding provides a denser frequency grid but does - not add spectral resolution. -* Apodization reduces endpoint artifacts but changes band widths and - amplitudes; report the selected function and its parameters. * Charge-flux spectra require physically meaningful partial charges and should not be interpreted as absolute IR intensities without further calibration. +Validity and interpretation +--------------------------- + +The frequency axis, and what sets it +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Two different parameters control the two different properties of the spectrum, +and they are easy to confuse. Write :math:`\Delta t` for ``time_step`` in ps, +:math:`W` for ``window`` in frames and :math:`F` for ``ftsize``. + +**The grid spacing is set by** ``ftsize``. PQAnalysis mirrors the padded +correlation into an even extension and labels the transform with + +.. math:: + + \Delta\tilde\nu = \frac{1}{2(F-1)\,\Delta t\,c} + \approx \frac{16.68}{(F-1)\,\Delta t[\mathrm{ps}]}\ \mathrm{cm}^{-1}. + +The axis starts at :math:`\Delta\tilde\nu` — there is no :math:`\tilde\nu = 0` +point — and runs up to :math:`F\,\Delta\tilde\nu`. For ``time_step = 0.001`` +and ``ftsize = 5000`` that is a 3.34 cm⁻¹ grid reaching 16682 cm⁻¹. + +**The upper limit is the Nyquist wavenumber**, set by the sampling interval +alone: + +.. math:: + + \tilde\nu_{\max} = \frac{1}{2\,\Delta t\,c} + \approx \frac{16.68}{\Delta t[\mathrm{ps}]}\ \mathrm{cm}^{-1}, + +which is 16678 cm⁻¹ for frames written every 1 fs and 1668 cm⁻¹ for frames +written every 10 fs. What matters is the interval between *written* frames, not +the integration time step of the underlying dynamics: an X-H stretch near +3000 cm⁻¹ needs a trajectory stride below about 5.5 fs to be represented at +all, and motion above the limit is aliased back into the spectrum rather than +discarded. The legacy axis is one grid point longer than Nyquist, +:math:`F/(F-1)\cdot\tilde\nu_{\max}`, and the last spectrum point duplicates +its predecessor; both are deliberate legacy conventions. + +.. note:: + + The axis carries a deliberate legacy calibration: the spacing is computed + with a period of :math:`2(F-1)` points although the underlying even + extension has :math:`2F-1` points. Reported wavenumbers are therefore high + by a factor :math:`(2F-1)/(2F-2)`. The absolute offset grows linearly with + wavenumber and reaches about half a grid spacing at the top of the axis, so + it is at most a sub-bin effect, but it is a systematic one. + +Resolution comes from the correlation length, not from padding +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The correlation extends to a maximum lag time :math:`T = W\,\Delta t`. +Truncating a correlation at :math:`T` convolves the spectrum with a kernel of +width + +.. math:: + + \delta\tilde\nu \approx \frac{1}{c\,T} + \approx \frac{33.4}{T[\mathrm{ps}]}\ \mathrm{cm}^{-1}, + +and features narrower than that are not resolved no matter how fine the grid +is. Two lines 20 cm⁻¹ apart merge into a single peak for :math:`T = 0.5` ps +(:math:`\delta\tilde\nu = 67` cm⁻¹) and separate cleanly for :math:`T = 2.5` ps +(:math:`\delta\tilde\nu = 13` cm⁻¹). Increasing ``ftsize`` beyond the number of +correlation points only interpolates the same information onto a denser grid; +resolving finer structure requires a longer ``window``, which in turn requires +a longer trajectory. + +.. warning:: + + ``ftsize`` also truncates. The correlation is zero-padded **or cut** to + ``ftsize`` points, so with ``ftsize`` smaller than ``window + 1`` everything + beyond the first ``ftsize`` lags is silently discarded before the transform. + The default ``ftsize`` is 2000 while the default ``window`` is 1000, so the + defaults are safe — but raising ``window`` without raising ``ftsize`` throws + the extra correlation away. Keep ``ftsize`` at least ``window + 1``. + +Apodization: leakage against band shape +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A correlation that has not decayed to zero at the end of the window produces +sinc-like ringing and leakage in the transform. An apodization window +suppresses the discontinuity, at the cost of widening every band and lowering +every peak [Harris1978]_. Always report which window and which parameters were +used; band widths from differently apodized spectra are not comparable. + +The ``exponential`` window multiplies the correlation by +:math:`\exp(-a\,t)` with :math:`a` = ``window_param`` in ps⁻¹. It simply adds +:math:`a` to the decay rate of the correlation, which broadens a Lorentzian +band by roughly + +.. math:: + + \Delta\tilde\nu_{\mathrm{apod}} \approx \frac{a}{\pi c} + \approx 10.6\,a[\mathrm{ps}^{-1}]\ \mathrm{cm}^{-1}. + +On a test band with a 2 ps dephasing time, the unapodized width is about +9 cm⁻¹, and ``window_param`` values of 2, 4 and 8 ps⁻¹ widen it to about 26, 47 +and 89 cm⁻¹ while the peak height drops to 28 %, 16 % and 8 % of its +unapodized value. Apodization strong enough to tame leakage is also strong +enough to dominate the linewidth, so a width read off an apodized spectrum is a +property of the window, not of the dynamics. + +.. warning:: + + ``hann`` and ``blackman`` do nothing at their default settings. Both are + built from ``window_start`` (default 0.0 ps) and ``window_stop`` + (default 1000.0 ps), and over a correlation of a few ps the resulting + factors deviate from unity by less than :math:`3\times10^{-5}` — the + spectrum is indistinguishable from ``window_function = none``. To use them, + set ``window_stop`` to the correlation length ``window * time_step``. With + ``window_stop = 2.5`` on a 2.5 ps correlation, ``hann`` widened the test + band from 9.2 to 15.0 cm⁻¹ and ``blackman`` to 17.5 cm⁻¹, with peak heights + falling by 38 % and 45 %. The ``exponential`` window is unaffected by this, + since it decays from ``window_start`` onwards. + + The legacy ``hann`` and ``blackman`` formulas are additionally non-standard + — the Hann window is mirrored and the Blackman denominators use the stop + index rather than the window width. Both quirks are reproduced deliberately; + see :func:`PQAnalysis.analysis.vacf.spectrum.apodization_window`. + +The normalization discards absolute magnitude +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The correlation is normalized to :math:`C(0)=1` before anything else happens: +the ``direct`` estimator divides each time origin by its own aggregate squared +velocity norm, and the ``fft`` estimator divides by its lag-zero value. The +cosine transform is linear, so the spectrum inherits that normalization and its +amplitudes are in arbitrary units. Relative peak *areas* within one spectrum are +meaningful — apodization broadens bands but conserves their area — while peak +*heights* are only comparable between spectra that used the same apodization. +Zero-padding does not rescale amplitudes; it samples the same envelope more +finely, so a coarse grid can under-read the apex of a narrow band by a few per +cent. Absolute intensities are not available at all, for the velocity spectrum +as much as for the charge-flux spectrum. + +The sums over atoms are also unweighted — no masses enter anywhere in the VACF +code. Each atom therefore contributes in proportion to its own mean squared +velocity, which at equipartition is proportional to :math:`1/m`, so light atoms +dominate a mixed-element selection. This is not the mass-weighted vibrational +density of states of the textbook definition. For element-resolved band +assignments, run separate analyses with a per-element ``target_selection``. + +Classical dynamics limits what a peak position means +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The spectrum describes the classical nuclear motion actually present in the +trajectory. PQAnalysis applies no quantum correction of any kind: no zero-point +energy, no harmonic quantum correction factor to the intensities, no frequency +scaling factor. Band positions therefore carry the classical-nuclei error and +the full anharmonic and thermal shift of the underlying dynamics at the +simulated temperature, and are not directly comparable to harmonic normal-mode +wavenumbers — see :doc:`vibrations` for the harmonic route. Comparisons with +experiment must state the temperature, the level of theory and the fact that +the peak positions are classical. + +Estimator choice changes the statistics of the tail +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ``method = direct`` (default) spawns an origin every ``gap`` frames while a + full window still fits. Every origin covers the full window, so every lag + from 0 to ``window`` is averaged over the same number of origins. +* ``method = fft`` uses every frame as an origin and ignores ``gap``, but + divides lag :math:`\tau` by its own origin count :math:`N-\tau`. Its origin + count *does* fall off with lag, so the far tail of the correlation is + progressively noisier — precisely the part of the correlation that determines + the low-wavenumber structure of the spectrum. It also holds all velocities in + memory. + +.. warning:: + + A velocity trajectory of exactly ``window`` frames with ``gap = 1`` takes + the legacy single-origin branch: one origin is spawned, the correlation is + an unaveraged single-origin estimate, and the final lag bin stays exactly + zero. Use a longer trajectory or a smaller ``window``. + Output and API -------------- @@ -93,3 +268,30 @@ transform. Discrete line spectra can be broadened independently with ``pqanalysis build_spectrum``; see :ref:`analysis-output-spectrum` for its output convention. + +References +---------- + +* [Rahman1964]_ introduced the velocity autocorrelation function as a + molecular-dynamics observable and describes its negative-lobe behavior in a + liquid. +* [Green1954]_ and [Kubo1957]_ establish the link between equilibrium time + correlation functions and transport coefficients. The time integral of the + unnormalized velocity autocorrelation function is the Green-Kubo expression + for the self-diffusion coefficient. +* [Wiener1930]_ and [Khintchine1934]_ prove that the autocorrelation function + and the power spectrum of a stationary process are a Fourier pair, which is + what the ``fft`` estimator exploits. +* [Dickey1969]_ interprets the transformed velocity autocorrelation function + as a vibrational density of states. +* [Thomas2013]_ covers vibrational density of states, charge-flux and dipole + routes to infrared spectra, and the effect of correlation depth and + windowing on band shapes. +* [Harris1978]_ tabulates the apodization windows and their trade-off between + sidelobe suppression and main-lobe broadening. +* [Allen2017]_ gives the time-origin averaging and sampling requirements for + correlation functions. +* [thhTools]_ is the legacy program family whose estimator and Fourier + conventions the default path reproduces. + +Full entries are listed in :doc:`../references`. diff --git a/docs/source/analyses/vibrations.rst b/docs/source/analyses/vibrations.rst index 1421b705..019d73fb 100644 --- a/docs/source/analyses/vibrations.rst +++ b/docs/source/analyses/vibrations.rst @@ -1,10 +1,271 @@ Vibrational Analysis ==================== -Vibrational analysis diagonalizes the mass-weighted Cartesian Hessian. Its -eigenvectors define normal modes and its eigenvalues determine signed -wavenumbers. Negative wavenumbers represent imaginary modes associated with -negative curvature of the potential-energy surface. +Vibrational analysis diagonalizes the mass-weighted Cartesian Hessian of a +single structure [Wilson1955]_. Its eigenvectors are the harmonic normal modes; +its eigenvalues give signed wavenumbers, force constants and reduced masses. +When partial charges are supplied, point-charge infrared intensities are +reported as well. The whole calculation is the harmonic approximation applied +to one isolated structure: no dynamics, temperature or anharmonicity enters it. + +Throughout this page :math:`N` is the number of atoms, :math:`i` indexes atoms, +:math:`a,b\in\{x,y,z\}` index Cartesian directions, and +:math:`\alpha,\beta\in\{1,\dots,3N\}` index Cartesian coordinates in the file +order :math:`x_1,y_1,z_1,x_2,\dots`. :math:`m_\alpha` is the mass in amu of the +atom owning coordinate :math:`\alpha`, and :math:`j` indexes normal modes. + +Mass-weighted Hessian +--------------------- + +The Hessian read from ``hessian_file`` is symmetrized, multiplied by the sign +factor :math:`s\in\{+1,-1\}` and mass-weighted, + +.. math:: + + H^{\mathrm{mw}}_{\alpha\beta} + = \frac{s}{2}\, + \frac{H_{\alpha\beta}+H_{\beta\alpha}}{\sqrt{m_\alpha m_\beta}} . + +Symmetrization is unconditional: a Hessian that is only approximately symmetric +is averaged with its transpose rather than rejected. + +Normal-mode eigenproblem +------------------------ + +PQAnalysis first assembles a trial matrix :math:`D` of external modes. Its +translational columns are + +.. math:: + + D^{\mathrm{trans}}_{(i,a),b} + = \frac{\sqrt{m_i}\,\delta_{ab}}{\sqrt{\sum_k m_k}} , + +and its rotational columns are mass-weighted rigid-body rotations, built from +the atomic positions relative to the center of mass and projected onto the +eigenvectors of the inertia tensor of the uncentered coordinates. Any +complete orthogonal basis leaves the spectrum unchanged, so this choice does +not affect the wavenumbers. A rotational column whose norm falls below +:math:`10^{-6}` times the larger of one and the biggest column norm is +discarded, which is what leaves a linear molecule with two rotations instead of +three. + +A complete QR factorization of :math:`D` supplies an orthonormal basis +:math:`Q\in\mathbb{R}^{3N\times 3N}` whose leading columns span these external +modes. The symmetrized transformed matrix is then diagonalized: + +.. math:: + + \bigl(Q^{\mathsf{T}}H^{\mathrm{mw}}Q\bigr)\,\mathbf{c}_j + = \lambda_j\,\mathbf{c}_j , + \qquad + \lambda_1\le\lambda_2\le\dots\le\lambda_{3N} . + +Because :math:`Q` is orthogonal, this is a similarity transformation and +:math:`\{\lambda_j\}` is exactly the spectrum of :math:`H^{\mathrm{mw}}`. The +external-mode basis orients the eigenvectors and defines the internal block +used by the sign heuristic below; it does not project translations and +rotations out of the reported spectrum. Those appear as the near-zero +eigenvalues of the full :math:`3N`-dimensional problem and are removed only by +the ``modes`` selection when mode files are written. + +The eigenvectors are transformed back to Cartesian displacements and +normalized, + +.. math:: + + l_{\alpha j} = \frac{(Q\mathbf{c}_j)_\alpha}{\sqrt{m_\alpha}} , + \qquad + e_{\alpha j} + = \frac{l_{\alpha j}}{\bigl(\sum_\beta l_{\beta j}^{2}\bigr)^{1/2}} , + \qquad + \sum_\alpha e_{\alpha j}^{2} = 1 , + +so the columns :math:`e_{\alpha j}` written to ``normal_modes_file`` are +dimensionless unit vectors. Modes are reported in order of increasing +:math:`\lambda_j`, so imaginary modes come first and the stiffest internal mode +comes last. + +Eigenvalues, wavenumbers and the unit chain +------------------------------------------- + +Each eigenvalue is converted to an angular frequency and then to a wavenumber, + +.. math:: + + \omega_j = \operatorname{sgn}(\lambda_j)\sqrt{\lvert\lambda_j\rvert\,C_u} , + \qquad + \tilde{\nu}_j = \frac{\omega_j}{2\pi c} , + \qquad + c = 2.99792458\times10^{10}\ \mathrm{cm\,s^{-1}} , + +with :math:`\omega_j` in rad·s⁻¹ and :math:`\tilde{\nu}_j` in cm⁻¹. The +constant :math:`C_u` is fixed by the ``unit`` key and carries the entire unit +chain from the Hessian file to s⁻²: + +.. list-table:: Conversion constants selected by ``unit`` + :class: pq-record-table + :header-rows: 1 + :widths: 14 30 56 + + * - ``unit`` + - Expected Hessian unit + - Factor :math:`C_u` taking :math:`\lambda_j` to s⁻² + * - ``kcal`` + - kcal·mol⁻¹·Å⁻² + - :math:`4184\times10^{23}` + * - ``ev`` + - eV·Å⁻² + - :math:`96485.307499\times10^{23}` + * - ``hartree`` + - hartree·bohr⁻² + - :math:`2\,625\,500.2\times(1.88972598857892\times10^{10})^{2}\times10^{3}` + +Each constant is the product of three conversions. For ``kcal``, the factor +:math:`4184` converts kcal to J, the factor :math:`10^{20}` converts Å⁻² to +m⁻², and the remaining :math:`10^{3}` comes from combining the molar energy +with the reciprocal atomic mass unit: because +:math:`1\ \mathrm{amu} = 10^{-3}\ \mathrm{kg\,mol^{-1}}/N_\mathrm{A}`, the +Avogadro constant cancels and leaves :math:`10^{3}\ \mathrm{kg^{-1}}`. That +cancellation is why no value of :math:`N_\mathrm{A}` appears anywhere in the +conversion. ``ev`` follows the same chain with +:math:`96485.307499\ \mathrm{J\,mol^{-1}}` per eV. ``hartree`` replaces the +Å⁻² step with +:math:`(1/a_0)^{2} = (1.88972598857892\times10^{10}\ \mathrm{m^{-1}})^{2}`, so +this option expects the Hessian in bohr⁻², while ``kcal`` and ``ev`` expect +Å⁻². Choosing the energy unit therefore also chooses the length unit. + +Imaginary modes and the ``hessian_sign`` heuristic +-------------------------------------------------- + +The square root is taken with a sign-preserving convention, +:math:`\operatorname{sgn}(x)\sqrt{\lvert x\rvert}`, so a negative eigenvalue +produces a negative :math:`\omega_j` and a negative wavenumber rather than an +imaginary number. A reported :math:`\tilde{\nu}_j < 0` therefore means an +imaginary mode of magnitude :math:`\lvert\tilde{\nu}_j\rvert` cm⁻¹, that is, +negative curvature of the potential-energy surface along that mode. + +The sign convention of the input file matters because Hessians are written +either as second derivatives of the energy or as derivatives of the forces, +which differ by a factor of :math:`-1`. In an input file ``hessian_sign`` +accepts ``positive`` (:math:`s=+1`), ``negative`` (:math:`s=-1`) and ``auto``. +The Python interface additionally accepts the numbers ``1`` and ``-1``. + +``auto`` resolves the convention from the curvature statistics of the internal +subspace. Let :math:`U` be the block of :math:`Q` spanning the complement of +the external modes, and let :math:`\lambda^{\mathrm{int}}` be the eigenvalues +of :math:`U^{\mathsf{T}}H^{\mathrm{mw}}U` evaluated with :math:`s=+1`. With the +tolerance + +.. math:: + + \tau = \sqrt{\varepsilon_{\mathrm{mach}}}\; + \max\bigl(1,\ \max_j\lvert\lambda^{\mathrm{int}}_j\rvert\bigr) , + \qquad + \sqrt{\varepsilon_{\mathrm{mach}}}\approx 1.49\times10^{-8} , + +the counts :math:`n_+ = \#\{\lambda^{\mathrm{int}}_j > \tau\}` and +:math:`n_- = \#\{\lambda^{\mathrm{int}}_j < -\tau\}` decide the sign: +:math:`s=-1` when :math:`n_- > n_+`, and :math:`s=+1` when :math:`n_+ > n_-`. +A tie is broken by the larger of +:math:`\sum\lvert\lambda^{\mathrm{int}}\rvert` over the positive and the +negative set. If the structure has no internal subspace at all — a single atom, +whose three coordinates are exhausted by the translations — the heuristic +returns :math:`s=+1`. + +The heuristic exists because a bound structure must have positive curvature +along most of its internal coordinates, so the sign that makes the majority of +internal eigenvalues positive is the physical one. This is also the only place +where the internal subspace is genuinely projected out. Being a majority vote, +it is reliable for minima and for transition states — one imaginary mode among +many real ones — and unreliable for structures far from any stationary point. +Set ``hessian_sign`` explicitly whenever the convention of the producing code +is known. + +Force constants, reduced masses and IR intensities +-------------------------------------------------- + +The reduced mass of a mode is the inverse squared length of its unnormalized +Cartesian displacement, + +.. math:: + + \mu_j + = \left(\sum_\alpha l_{\alpha j}^{2}\right)^{-1} + = \left(\sum_\alpha + \frac{(Q\mathbf{c}_j)_\alpha^{2}}{m_\alpha}\right)^{-1} , + +reported in amu. A purely translational mode reports the total mass divided +by the number of atoms, 6.01 amu for a water molecule; a localized hydrogen +stretch approaches 1 amu. + +The force constant combines the frequency with the reduced mass, + +.. math:: + + k_j = \frac{\omega_j^{2}\,\mu_j}{6.022\times10^{28}} , + +in mdyn·Å⁻¹. The single constant applies both +:math:`1\ \mathrm{amu} = 1.66054\times10^{-27}\ \mathrm{kg}` and +:math:`1\ \mathrm{mdyn\,\AA^{-1}} = 100\ \mathrm{N\,m^{-1}}`. It uses the +rounded value :math:`6.022`, so force constants carry a systematic offset of +about :math:`2\times10^{-5}` relative to the CODATA constant. That is far below +any physical uncertainty in a Hessian, but it is visible when comparing digit +by digit against another program. + +With a ``moldescriptor_file`` every atom carries a fixed partial charge +:math:`q_i` in units of the elementary charge, and the infrared intensity is + +.. math:: + + I_j = \frac{42.2561}{\mu_j} + \sum_{a\in\{x,y,z\}} + \left(\frac{1}{0.2081943\,\lVert e_j\rVert} + \sum_i q_i\,e_{(i,a)\,j}\right)^{2} , + +in km·mol⁻¹. The inner sum :math:`\sum_i q_i e_{(i,a)j}` is the derivative of +the point-charge dipole moment along mode :math:`j` [Person1974]_; dividing by +:math:`0.2081943\ \mathrm{e\,\AA\,D^{-1}}` expresses it in D·Å⁻¹, and +:math:`42.2561` converts +:math:`(\mathrm{D\,\AA^{-1}})^{2}\,\mathrm{amu^{-1}}` to km·mol⁻¹. The norm +:math:`\lVert e_j\rVert` equals one by construction and acts only as a guard. + +External modes and the ``modes`` selection +------------------------------------------ + +A non-linear structure has three translational and three rotational modes; a +linear one has three and two. At an exact stationary point these external modes +carry no curvature and appear at the bottom of the spectrum with +:math:`\tilde{\nu}\approx 0`. In practice they are small but non-zero, and they +may be slightly negative, because the Hessian was computed at a finite +convergence threshold and in finite precision. + +``modes`` selects which modes reach ``modes_prefix`` and ``modes_file``, +comparing wavenumbers against the threshold :math:`\theta` set by +``modes_threshold`` (default :math:`10^{-8}` cm⁻¹): + +.. list-table:: ``modes`` selection rules + :class: pq-record-table + :header-rows: 1 + :widths: 24 76 + + * - Value + - Selected modes + * - ``all`` (default) + - Every mode, in order of increasing wavenumber + * - ``nonzero`` + - :math:`\lvert\tilde{\nu}_j\rvert > \theta`, keeping imaginary modes + * - ``positive`` + - :math:`\tilde{\nu}_j > \theta`, dropping imaginary modes + * - Numbers + - Explicit one-based mode numbers: an integer, a list or a range + +Because the default threshold is only :math:`10^{-8}` cm⁻¹, ``positive`` does +not by itself remove residual external modes. For the bundled H₂O fixture it +keeps the three translational modes at 0.02, 0.22 and 0.30 cm⁻¹ alongside the +three internal modes at 1493, 3669 and 3784 cm⁻¹, and drops the three +rotational modes, which come out imaginary between :math:`-50` and +:math:`-37` cm⁻¹. Raise ``modes_threshold`` to a few cm⁻¹, or higher, when the +intent is "internal modes only". Internal-mode spectrum ---------------------- @@ -35,30 +296,98 @@ Minimal input ``structure_file`` may be a PQ restart or a single-frame XYZ file. ``unit`` describes the Hessian energy unit and accepts ``kcal``, ``hartree`` or ``ev``. -``hessian_sign = auto`` evaluates both supported sign conventions and chooses -the one with more non-negative vibrational modes. - -Scientific checks ------------------ - -* A stable, fully optimized minimum should not contain genuine imaginary - internal modes. Small values can arise from incomplete optimization or - numerical noise. -* Translational and rotational near-zero modes depend on boundary conditions, - molecular geometry and numerical precision. -* IR intensities require a ``moldescriptor_file`` containing partial charges. -* The Hessian coordinate order, structure atom order and selected unit must - agree exactly. +IR intensities are written only when a ``moldescriptor_file`` supplies partial +charges. Mode output ----------- -``normal_modes_file`` stores the dimensionless Cartesian mode matrix. -``modes_prefix`` writes sinusoidal multi-frame XYZ animations, while -``modes_file`` writes one extended-XYZ image per selected mode with vectors and -metadata. Explicit mode numbers are one-based. +``normal_modes_file`` stores the dimensionless Cartesian mode matrix +:math:`e_{\alpha j}`. ``modes_file`` writes one extended-XYZ image per selected +mode, carrying the mode vectors and metadata. ``modes_prefix`` writes one +sinusoidal animation per selected mode, with frame :math:`k` of +``modes_frames`` (default 30) at + +.. math:: + + \mathbf{x}_i(\varphi_k) = \mathbf{x}_i^{0} + \sin(\varphi_k)\,\mathbf{d}_i , + \qquad + \varphi_k = \frac{2\pi k}{n_{\mathrm{frames}}} . + +By default the displacement :math:`\mathbf{d}_i` is the mode scaled so that the +largest atomic displacement equals ``modes_amplitude`` (default 0.25 Å). If +``modes_temperature`` :math:`T` is given, the mode is instead scaled by the +classical thermal factor + +.. math:: + + \mathbf{d}_i = \mathbf{e}_{ij}\sqrt{\frac{k_\mathrm{B}T}{E_j}} , + \qquad + E_j = \lvert\tilde{\nu}_j\rvert\times + 1.2398419843320026\times10^{-4}\ \mathrm{eV\,cm} , + +with :math:`k_\mathrm{B} = 8.617333262145\times10^{-5}\ \mathrm{eV\,K^{-1}}` +and :math:`E_j` the mode energy obtained from the wavenumber. Modes whose +energy lies at or below the threshold fall back to the fixed amplitude, which +keeps near-zero modes from being drawn with a diverging excursion. Both +scalings are display conventions, not physical vibrational amplitudes. + +Validity and interpretation +--------------------------- + +A trustworthy result has :math:`3N` modes in total, of which six — five for a +linear structure — are external and small compared with the softest internal +mode, and :math:`3N-6` are internal and positive at a minimum, or positive +except for exactly one imaginary mode at a transition state. Residual external +modes of a few tens of cm⁻¹, sometimes negative, indicate an incompletely +optimized geometry or a numerically noisy Hessian rather than physical soft +modes. + +The method does not apply, or needs care, in these situations: + +* **Away from a stationary point.** The harmonic expansion assumes vanishing + gradients. PQAnalysis projects out neither the gradient nor the external + modes, so residual forces leak into the translational and rotational modes + and mix into the low-wavenumber internal modes. +* **Periodic systems.** The external-mode construction uses a center of mass + and an inertia tensor, which presumes an isolated structure. A Hessian from a + periodic calculation can still be diagonalized, but the rotational trial + vectors and the interpretation of the near-zero modes are not meaningful. +* **Unit and ordering mismatches.** The Hessian coordinate order must match the + structure atom order exactly, and the energy unit must match ``unit``, + including the bohr length convention implied by ``hartree``. A mismatch + yields a plausible-looking spectrum on the wrong scale, not an error. +* **Comparison with experiment.** These are harmonic wavenumbers. They + systematically exceed observed fundamentals, and PQAnalysis applies no + empirical scaling factor. Finite-temperature and anharmonic band shapes come + from the time-correlation route in :doc:`vacf` instead [Thomas2013]_. +* **IR intensities.** Fixed atomic point charges carry no charge flux and no + electronic polarization, so :math:`I_j` reproduces relative band strengths of + strongly polar motions at best. Do not report them as quantitative + absorption coefficients. +* **Degenerate modes.** Within a degenerate set the individual eigenvectors are + arbitrary up to a rotation inside that subspace. Wavenumbers, force constants + and the summed intensity are well defined; individual mode vectors are not. + +Output and API +-------------- See :ref:`analysis-output-vibrations` for every table and file schema. The main entry point is :func:`PQAnalysis.analysis.vibrational.api.vibrations`; direct calculations use :func:`PQAnalysis.analysis.vibrational.vibrational_analysis.calculate_from_system`. + +References +---------- + +* [Wilson1955]_ is the standard treatment of the mass-weighted Hessian + eigenvalue problem, normal coordinates and the separation of translation and + rotation. +* [Person1974]_ defines infrared intensities through dipole moment + derivatives and polar tensors, the quantity the partial-charge model + approximates. +* [Thomas2013]_ compares this static normal-mode route with spectra obtained + from molecular-dynamics time correlation functions, which PQAnalysis + provides through :doc:`vacf`. + +Full entries are listed in :doc:`../references`. diff --git a/docs/source/index.rst b/docs/source/index.rst index 24885938..dd8b224f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -90,6 +90,7 @@ package ownership boundaries. Command Line Files and Formats Package Reference + references .. toctree:: :hidden: diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 00000000..8f548efb --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,138 @@ +.. _references: + +References +========== + +The entries below are the primary sources for the estimators PQAnalysis +implements. Each analysis page cites the entries that define the quantity it +reports, so a documented estimator can be checked against its original +definition rather than against this implementation alone. + +Molecular simulation and liquid-state theory +-------------------------------------------- + +.. [Allen2017] Allen, M. P.; Tildesley, D. J. *Computer Simulation of + Liquids*, 2nd ed.; Oxford University Press: Oxford, 2017. + ISBN 978-0-19-880319-5. + `doi:10.1093/oso/9780198803195.001.0001 + `__ + +.. [Frenkel2002] Frenkel, D.; Smit, B. *Understanding Molecular Simulation: + From Algorithms to Applications*, 2nd ed.; Academic Press: San Diego, + 2002. ISBN 978-0-12-267351-1. + `doi:10.1016/B978-0-12-267351-1.X5000-7 + `__ + +.. [Hansen2013] Hansen, J.-P.; McDonald, I. R. *Theory of Simple Liquids: + with Applications to Soft Matter*, 4th ed.; Academic Press: Oxford, 2013. + ISBN 978-0-12-387032-2. + `doi:10.1016/C2010-0-66723-X `__ + +Transport coefficients and time correlation functions +------------------------------------------------------ + +.. [Einstein1905] Einstein, A. Über die von der molekularkinetischen Theorie + der Wärme geforderte Bewegung von in ruhenden Flüssigkeiten suspendierten + Teilchen. *Annalen der Physik* **1905**, *322* (8), 549-560. + `doi:10.1002/andp.19053220806 + `__ + +.. [Green1954] Green, M. S. Markoff Random Processes and the Statistical + Mechanics of Time-Dependent Phenomena. II. Irreversible Processes in + Fluids. *The Journal of Chemical Physics* **1954**, *22* (3), 398-413. + `doi:10.1063/1.1740082 `__ + +.. [Kubo1957] Kubo, R. Statistical-Mechanical Theory of Irreversible + Processes. I. General Theory and Simple Applications to Magnetic and + Conduction Problems. *Journal of the Physical Society of Japan* **1957**, + *12* (6), 570-586. + `doi:10.1143/JPSJ.12.570 `__ + +.. [Rahman1964] Rahman, A. Correlations in the Motion of Atoms in Liquid + Argon. *Physical Review* **1964**, *136* (2A), A405-A411. + `doi:10.1103/PhysRev.136.A405 + `__ + +Spectra from time correlation functions +---------------------------------------- + +.. [Wiener1930] Wiener, N. Generalized harmonic analysis. *Acta Mathematica* + **1930**, *55*, 117-258. + `doi:10.1007/BF02546511 `__ + +.. [Khintchine1934] Khintchine, A. Korrelationstheorie der stationären + stochastischen Prozesse. *Mathematische Annalen* **1934**, *109* (1), + 604-615. + `doi:10.1007/BF01449156 `__ + +.. [Dickey1969] Dickey, J. M.; Paskin, A. Computer Simulation of the Lattice + Dynamics of Solids. *Physical Review* **1969**, *188* (3), 1407-1418. + `doi:10.1103/PhysRev.188.1407 + `__ + +.. [Thomas2013] Thomas, M.; Brehm, M.; Fligg, R.; Vöhringer, P.; Kirchner, B. + Computing vibrational spectra from ab initio molecular dynamics. + *Physical Chemistry Chemical Physics* **2013**, *15* (18), 6608-6622. + `doi:10.1039/C3CP44302G `__ + +.. [Harris1978] Harris, F. J. On the use of windows for harmonic analysis + with the discrete Fourier transform. *Proceedings of the IEEE* **1978**, + *66* (1), 51-83. + `doi:10.1109/PROC.1978.10837 + `__ + +Normal modes and infrared intensities +-------------------------------------- + +.. [Wilson1955] Wilson, E. B., Jr.; Decius, J. C.; Cross, P. C. *Molecular + Vibrations: The Theory of Infrared and Raman Vibrational Spectra*; + McGraw-Hill: New York, 1955. Reprinted by Dover: New York, 1980. + ISBN 978-0-486-63941-3. + +.. [Person1974] Person, W. B.; Newton, J. H. Dipole moment derivatives and + infrared intensities. I. Polar tensors. *The Journal of Chemical Physics* + **1974**, *61* (3), 1040-1049. + `doi:10.1063/1.1681972 `__ + +.. _software-provenance: + +Software provenance +------------------- + +Several PQAnalysis kernels reproduce the arithmetic of older programs bit for +bit so that historical results remain reproducible. That provenance is +recorded here as software attribution, not as literature. + +.. [thhTools] The ``thh_tools`` collection of legacy analysis programs: the + ``RDF`` C code, the ``Diffcalc`` mean-square-displacement code, the + ``FreqCalc`` and ``Fluxfreqcalc`` correlation codes, the ``ftvac`` + (``ft.f``) Fourier transformation code and ``thh_momentum/equipartition.jl``. + The collection is not publicly distributed and has no release version or + DOI. PQAnalysis reproduces its operation order only on the compatibility + paths described on the individual analysis pages, and pins that behavior + with the parity fixtures described in :doc:`developerGuide/validation`. + +.. _citing-pqanalysis: + +Citing PQAnalysis +----------------- + +PQAnalysis has no journal article, no ``CITATION.cff`` file and no minted DOI. +Do not cite a DOI for it, because none exists. + +Cite the software by repository and by the exact release you ran: + +.. code-block:: text + + PQAnalysis (version ), MolarVerse. + https://github.com/MolarVerse/PQAnalysis + +Report the version string from ``pqanalysis --version`` or from +``PQAnalysis.__version__``. Reported analyses should also name the +simulation engine that produced the input data, normally +`PQ `__, and the method-specific settings +that change the reported numbers, such as bin width, correlation window, +apodization function or Hessian unit. + +If a DOI is minted for a future release, cite that DOI instead of this +section.