diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8480df72..3c0c1171 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,62 +1,53 @@ -# 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: 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: + path: docs/build/html - - 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 + 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: Configure GitHub Pages + uses: actions/configure-pages@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 + 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/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..26c851a1 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. +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. -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. +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 @@ -19,22 +24,29 @@ 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: +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. - python -m pytest - -Use squash merges for pull requests. The pull request title becomes the commit -message on the target branch, so PR titles must follow -[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): +Pull request titles must follow +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/); CI +validates them. Keep individual commits scoped because multi-commit pull +requests may retain their commit history: feat: add a new analysis command fix(io): handle missing trajectory data 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/_ext/pq_cli_tables.py b/docs/source/_ext/pq_cli_tables.py new file mode 100644 index 00000000..17d0fe85 --- /dev/null +++ b/docs/source/_ext/pq_cli_tables.py @@ -0,0 +1,316 @@ +""" +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 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 +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 ast +import functools + +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 +from sphinx.util import logging +from sphinx.util.docutils import SphinxDirective + +logger = logging.getLogger(__name__) + +_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 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 + ------- + set[str] + The names of all registered ``pqanalysis`` subcommands. + + Raises + ------ + RuntimeError + 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")) + + commands = set() + + for node in ast.walk(tree): + if not isinstance(node, ast.Assign): + continue + + targets = { + target.id + for target in node.targets if isinstance(target, ast.Name) + } + + if _REGISTRY_NAME not in targets: + continue + + if not isinstance(node.value, ast.Dict): + continue + + 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( + 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 + + +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/_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..b60a9891 --- /dev/null +++ b/docs/source/_plots/vacf.py @@ -0,0 +1,90 @@ +"""Analytical two-band VACF and its PQAnalysis spectrum.""" + +import matplotlib.pyplot as plt +import numpy as np + +from PQAnalysis.analysis.vacf.spectrum import vacf_spectrum + +from _style import COLORS, apply_style + + +apply_style((6.2, 5.5)) + +time = np.arange(0.0, 0.5005, 0.0005) +correlation = ( + 0.70 * np.exp(-(time / 0.22) ** 2) + * np.cos(2.0 * np.pi * 9.0 * time) + + 0.30 * np.exp(-(time / 0.12) ** 2) + * np.cos(2.0 * np.pi * 18.0 * time) +) + +wavenumbers, amplitudes, windowed_correlation = vacf_spectrum( + time, + correlation, + ftsize=5000, + window_function="exponential", + window_param=4.0, +) +display_range = wavenumbers <= 1000.0 +wavenumbers = wavenumbers[display_range] +amplitudes = amplitudes[display_range] +amplitudes /= amplitudes.max() + +figure, (correlation_axis, spectrum_axis) = plt.subplots( + 2, + 1, + gridspec_kw={"height_ratios": (1.25, 1.0)}, +) + +correlation_axis.plot( + 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, + color=COLORS["muted"], + linestyle=":", + linewidth=1.0, +) +correlation_axis.set_title( + "(a) Normalized VACF", + loc="left", + fontsize=9.5, + fontweight="bold", + pad=8, +) +correlation_axis.set_xlabel("Lag time, t / ps") +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, + amplitudes, + color=COLORS["orange"], +) +spectrum_axis.set_title( + "(b) Exponential-window spectrum", + loc="left", + fontsize=9.5, + fontweight="bold", + pad=8, +) +spectrum_axis.set_xlabel("Wavenumber, ν̃ / cm⁻¹") +spectrum_axis.set_ylabel("Relative amplitude") +spectrum_axis.set_xlim(0.0, 1000.0) +spectrum_axis.set_ylim(0.0, 1.05) + +figure.tight_layout(h_pad=1.4) +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 d4bed75f..943b20f4 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -1,34 +1,181 @@ -@import url("theme.css"); +:root { + --pq-plot-background: #fff; +} -.wy-nav-content { - max-width: 80%; +.sidebar-brand { + flex-direction: row; + align-items: center; + gap: 0.75rem; + padding-block: 0.75rem; } -dl.py.class { - dt.sig.sig-object.py { - display: block !important; - } +.sidebar-logo-container { + display: flex; + flex: 0 0 4.5rem; + align-items: center; + margin: 0; +} + +.sidebar-logo { + width: 4.5rem; + margin: 0; +} + +.sidebar-brand-text { + margin: 0; + font-size: 1.35rem; + font-weight: 700; + line-height: 1.1; + letter-spacing: 0; +} + +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; } -.py.property { - display: block !important; +@media (max-width: 44rem), (max-height: 32rem) { + .back-to-top { + display: none !important; + } } -.sig.sig-object.py dl { - margin-block-end: 0.0em; +@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"; + } - & dd { - margin-bottom: 0.0em; + table.pq-types-table td:nth-child(2)::before { + content: "Role"; + } + + table.pq-package-reference-table td:nth-child(2)::before { + content: "Scope"; } } -.wy-table-responsive table.analysis-output-columns { +@media (max-width: 24rem) { + article h1 { + font-size: 2rem; + } +} + +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..86c9a1c2 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 maintained 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..6985cfde --- /dev/null +++ b/docs/source/analyses/index.rst @@ -0,0 +1,49 @@ +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. + +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 + + * - 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_{vv}(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 + +The method pages define each estimator, its assumptions and its interpretation +limits. File columns and units are specified once in +:ref:`analysisOutputFiles`. Programmatic entry points are listed in the +:doc:`../reference/functions`. + +.. 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..9bb3e639 --- /dev/null +++ b/docs/source/analyses/momentum.rst @@ -0,0 +1,135 @@ +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) , + +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 +------------------ + +.. code-block:: console + + $ pqanalysis check_momentum velocity.vel \ + --selection all \ + --output momentum.dat + +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. + +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: + +* 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. + +The compatibility path multiplies and sums atoms in the same order as the +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 new file mode 100644 index 00000000..3135f493 --- /dev/null +++ b/docs/source/analyses/msd.rst @@ -0,0 +1,264 @@ +Mean Square Displacement +======================== + +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:: + + \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. + +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 +------------- + +.. 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. + +File-backed orthorhombic trajectories use a bounded compatibility path that +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, 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, :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 +-------------- + +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 new file mode 100644 index 00000000..bfa1fa4f --- /dev/null +++ b/docs/source/analyses/rdf.rst @@ -0,0 +1,234 @@ +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 [Hansen2013]_. For histogram bin :math:`i`, +PQAnalysis uses the standard simulation estimator [Allen2017]_, + +.. 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. + +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 +------------- + +.. 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. + +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 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. + +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. + +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 +-------------- + +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`. + +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 new file mode 100644 index 00000000..1a58c20c --- /dev/null +++ b/docs/source/analyses/vacf.rst @@ -0,0 +1,297 @@ +VACF and Spectra +================ + +The normalized velocity autocorrelation function describes how rapidly atomic +velocities lose memory of their initial direction [Rahman1964]_, [Allen2017]_: + +.. math:: + + C_{vv}(t) = + \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 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. 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 [Harris1978]_. The optional ``windowed_out_file`` records that +copy. + +Correlation and spectrum +------------------------ + +.. plot:: _plots/vacf.py + :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 +------------- + +.. 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`` 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. +* In liquids, negative regions often indicate backscattering or cage motion; + in solids, sign oscillations reflect bound vibrational motion. +* 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 +-------------- + +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. + +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 new file mode 100644 index 00000000..019d73fb --- /dev/null +++ b/docs/source/analyses/vibrations.rst @@ -0,0 +1,393 @@ +Vibrational Analysis +==================== + +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 +---------------------- + +.. 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 +------------- + +.. 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``. +IR intensities are written only when a ``moldescriptor_file`` supplies partial +charges. + +Mode output +----------- + +``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/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 d7f93d0e..e7417a72 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,43 +1,46 @@ -# 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 -sys.path.insert(0, os.path.abspath('../../')) +SOURCE_DIR = Path(__file__).resolve().parent +DOCS_DIR = SOURCE_DIR.parent +PROJECT_ROOT = DOCS_DIR.parent -project = 'PQAnalysis' -copyright = '2023, Jakob Gamper, Josef M. Gallmetzer, Clarissa A. Seidler' -author = 'Jakob Gamper, Josef M. Gallmetzer, Clarissa A. Seidler' +sys.path.insert(0, str(PROJECT_ROOT)) +sys.path.insert(0, str(SOURCE_DIR / "_plots")) +sys.path.insert(0, str(SOURCE_DIR / "_ext")) -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration +project = "PQAnalysis" +author = "the PQAnalysis authors" +copyright = "2023-2026, the PQAnalysis authors" + +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", + "matplotlib.sphinxext.plot_directive", + "pq_cli_tables", + "myst_parser", + "sphinx_copybutton", ] -# Napoleon settings napoleon_google_docstring = True napoleon_numpy_docstring = True napoleon_include_init_with_doc = False @@ -50,92 +53,107 @@ 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'] +copybutton_prompt_text = r">>> |\.\.\. |\$ " +copybutton_prompt_is_regexp = True -# The master toctree document. -master_doc = 'index' +plot_formats = [("svg", 96)] +plot_html_show_formats = False +plot_html_show_source_link = False +plot_include_source = False -# 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' +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/" -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +# 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}" -# 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..9b5535e5 --- /dev/null +++ b/docs/source/data/index.rst @@ -0,0 +1,68 @@ +Files and Formats +================= + +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. + +Four file contracts govern analysis 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 +---------------------- + +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/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..24dffd49 --- /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, 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. + +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 66c7d397..f40ebec5 100644 --- a/docs/source/developerGuide/developerGuide.rst +++ b/docs/source/developerGuide/developerGuide.rst @@ -1,141 +1,123 @@ .. _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 integrates feature and fix branches on ``dev`` and releases from +``main``. The pages below define package ownership, extension steps, +validation requirements and release operations. -***************** -Coding Guidelines -***************** +Extension path +-------------- -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. +.. list-table:: Analysis implementation path + :class: pq-record-table pq-extension-table + :header-rows: 1 + :widths: 24 38 38 -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. + * - 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 -***************** -How to Contribute -***************** +.. toctree:: + :maxdepth: 1 -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: + architecture + adding-analysis + validation + release +Local environment +----------------- - #. Fork the project on Github. (not necessary if you are a member of the project) +Install development, test and documentation dependencies in an isolated +environment: - #. Clone your fork locally: - - .. code:: bash +.. code-block:: console - $ git clone https://github.com/MolarVerse/PQAnalysis.git + $ 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]" - #. Initialize git flow with the following settings (if not specified default settings are used) +Quality gates +------------- - .. code:: bash +``pytest.sh`` runs the suite with debug runtime type checking and repeats it +with release settings: - [master] main - [develop] dev - [version tag prefix] v +.. code-block:: console - #. Create a feature branch for your contribution: - - .. code:: bash + $ bash pytest.sh + $ bash pytest.sh tests/analysis/rdf -q - $ git flow feature start +Run Pylint against the package and retain a score above the CI threshold of +9.75: +.. code-block:: console - #. Commit your changes to your feature branch and publish your feature branch: - - .. code:: bash + $ python -m pylint PQAnalysis --persistent n - $ git add - $ git commit -m "fix: describe the bug fix" - $ git flow feature publish - - #. Create a pull request on Github. +Public Python interfaces use NumPy-style docstrings. Document parameters, +returns, raised exceptions, units and array shapes. Inspect coverage with: - #. 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. +.. code-block:: console - #. 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. + $ docstr-coverage PQAnalysis - #. 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: - -.. code:: bash - - $ pip install -e ".[docs]" # install the project with the documentation dependencies - -To build the documentation, use the following command: - -.. code:: bash - - $ cd docs - - $ make html - -In order to view the documentation, open the following file in a web browser: - -.. code:: bash - - $ open build/html/index.html - -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: - -.. code:: bash - - $ docstr-coverage PQAnalysis - -******* -Testing -******* - -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: +------------- -.. code:: bash +Build HTML and check external links with warnings treated as errors: - $ pip install -e ".[test]" # install the project with the test dependencies +.. code-block:: console - $ python -m pytest + $ 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 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. +The API reference is generated from package modules when Sphinx starts. Do not +hand-edit generated files under ``docs/source/code``. Add public callables to +:doc:`../reference/functions`, and keep implementation guidance in this +development section. -Last, if any additional dependencies are required for testing, please add them to the ``pyproject.toml`` file under the ``[project.optional-dependencies]`` section. +Executable figures under ``docs/source/_plots`` must be deterministic. Captions +must identify analytical models, versioned validation fixtures and physical +benchmark results correctly. -********************** -Performance Validation -********************** +Pull requests +------------- -File-backed VACF, MSD, RDF and momentum analyses use bounded compiled fast -paths. A batch path must preserve the numeric operation order of its streaming -fallback and must return to that fallback when the configured memory limit is -exceeded. Parallel work is restricted to independent lag ranges, frames or -private integer histograms; floating-point reductions within one legacy result -must not be reordered. +Feature and fix pull requests normally target ``dev``. Release pull requests +merge ``dev`` into ``main``. Use a Conventional Commits title, such as +``feat: add a new analysis command`` or +``fix(io): handle missing trajectory data``; CI validates the title. Keep each +commit scoped and reviewable because multi-commit pull requests may retain +their individual commits. -Install the benchmark dependency and run the focused benchmark suite with: +Enable the optional local commit-message hook with: -.. code:: bash +.. code-block:: console - $ pip install -e ".[test,benchmark]" - $ pytest -c benchmarks/pytest.ini benchmarks --benchmark-only + $ git config core.hooksPath .githooks -Store a baseline with ``--benchmark-json=baseline.json`` and compare a changed -branch with ``--benchmark-compare=baseline.json``. Runtime assertions do not -belong in CI because host load is variable. Every optimization must instead -pass the compiled and fallback tests plus the relevant fixed-bit legacy oracle -before its benchmark result is considered. +Before review, run the focused tests for every modified ownership boundary and +the relevant strict documentation builds. 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..2a53a450 --- /dev/null +++ b/docs/source/developerGuide/validation.rst @@ -0,0 +1,114 @@ +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. + +Compatibility kernels that claim fixed-bit legacy behavior must preserve the +legacy operation order and pass the corresponding exact oracle. General +kernels may accumulate values in a different order from NumPy fallbacks; their +parity tolerance should cover only the expected summation difference. + +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 + +Performance validation +---------------------- + +File-backed VACF, MSD, RDF and momentum analyses use bounded compiled paths. +An optimized path must return to its streaming fallback when its memory or +input-shape requirements are not met. Parallel work may divide independent lag +ranges or frames, or use private integer histograms. It must not reorder a +floating-point reduction covered by a fixed-bit compatibility guarantee. + +Install the benchmark dependency and run the focused suite with: + +.. code-block:: console + + $ python -m pip install -e ".[test,benchmark]" + $ pytest -c benchmarks/pytest.ini benchmarks --benchmark-only + +Store the parent result with ``--benchmark-json=baseline.json`` and compare a +changed branch with ``--benchmark-compare=baseline.json``. Record input size, +selection, window, gap, host and median wall time. Runtime thresholds do not +belong in CI because runner load is variable; compiled, fallback and fixed-bit +tests remain mandatory regardless of benchmark results. + +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 new file mode 100644 index 00000000..31031483 --- /dev/null +++ b/docs/source/getting-started.rst @@ -0,0 +1,82 @@ +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 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 +---------- + +* :doc:`analyses/index` compares the physical observables and required data. +* :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 1580bbe1..dd8b224f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,23 +1,100 @@ -.. 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 -########## +========== + +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:`Python functions ` | :doc:`Develop PQAnalysis ` + +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 + +Analysis methods +---------------- + +.. list-table:: Implemented observables + :class: pq-record-table pq-method-table + :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 + +Python interface +---------------- + +The public analysis functions use the same validated input readers and +scientific kernels as the command line: + +.. code-block:: python + + from PQAnalysis.analysis import rdf, read_analysis_table + + rdf("rdf.in", export_files=["rdf.csv"]) + table = read_analysis_table("rdf.csv") + +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 required +implementation steps and :doc:`Architecture ` for +package ownership boundaries. .. toctree:: :hidden: - :maxdepth: -1 - - userGuide/userGuide - developerGuide/developerGuide - code/PQAnalysis.rst + :maxdepth: 2 + :caption: Use PQAnalysis -Welcome to PQAnalysis's documentation! -====================================== + getting-started + analyses/index + Python Functions + Command Line + Files and Formats + Package Reference + references -:ref:`userGuide` +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: Develop PQAnalysis -:ref:`developerGuide` + developerGuide/developerGuide diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst new file mode 100644 index 00000000..d5f81ec9 --- /dev/null +++ b/docs/source/reference/api.rst @@ -0,0 +1,55 @@ +Package Reference +================= + +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 +---------- + +.. list-table:: Principal data types + :class: pq-record-table pq-types-table + :header-rows: 1 + :widths: 34 66 + + * - 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 + + * - 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, the function index for +callable workflows and the generated reference for implementation details. diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst new file mode 100644 index 00000000..d53e5876 --- /dev/null +++ b/docs/source/reference/cli.rst @@ -0,0 +1,69 @@ +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 + +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 +----------------- + +.. 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. + +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>`. + +.. pq-cli-covered:: + + convert + +Structure and trajectory conversion +----------------------------------- + +.. 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 +--------------------------- + +.. 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. diff --git a/docs/source/reference/functions.rst b/docs/source/reference/functions.rst new file mode 100644 index 00000000..00d6e8da --- /dev/null +++ b/docs/source/reference/functions.rst @@ -0,0 +1,84 @@ +.. _function-index: + +Function Index +============== + +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 +------------------ + +.. 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/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. diff --git a/docs/source/userGuide/analysisOutputFiles.rst b/docs/source/userGuide/analysisOutputFiles.rst index 3415a52d..d54bcb00 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. @@ -195,7 +194,7 @@ The ideal-gas pair count for the shell is * - 1 - Bin-center distance - :math:`r_i = (r_i^- + r_i^+) / 2` - - Angstrom + - Å * - 2 - Radial distribution function - :math:`g_i = H_i / E_i` @@ -208,7 +207,7 @@ The ideal-gas pair count for the shell is * - 4 - Density-normalized shell population - :math:`H_i / (\rho_T N_R N_F) = g_i\Delta V_i` - - Angstrom\ :sup:`3` + - ų * - 5 - Ideal-gas pair-count residual - :math:`H_i - E_i`; positive values are an excess and negative values @@ -242,15 +241,15 @@ The ``msd`` command writes the legacy Diffcalc layout to ``out_file``. * - 2 - :math:`\mathrm{MSD}_x` - Mean squared displacement along x - - Angstrom\ :sup:`2` + - Ų * - 3 - :math:`\mathrm{MSD}_y` - Mean squared displacement along y - - Angstrom\ :sup:`2` + - Ų * - 4 - :math:`\mathrm{MSD}_z` - Mean squared displacement along z - - Angstrom\ :sup:`2` + - Ų The total MSD is the sum of columns 2 through 4. It is returned by the Python API but is not repeated in the file. If ``time_step`` is provided, multiply @@ -295,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 @@ -340,7 +339,7 @@ output. * - 1 - Wavenumber - Regular output grid from ``--min`` to the exclusive ``--max`` - - cm\ :sup:`-1` + - cm⁻¹ * - 2 - Broadened intensity - Sum of the Gaussian or Lorentzian peak-height profiles @@ -373,7 +372,7 @@ reading the value as float64 preserves the calculated bit pattern. * - 2 - Scaled momentum norm - ``scale`` multiplied by :math:`\left|\sum_i m_i\mathbf{v}_i\right|` - - Set by ``--scale``; default is amu Angstrom fs\ :sup:`-1` + - Set by ``--scale``; default is amu·Å·fs⁻¹ .. _analysis-output-vibrations: @@ -403,15 +402,15 @@ The accompanying ``SYMBOLS`` line provides the Unicode scientific notation. * - 1 - Signed wavenumber - Always; negative values represent imaginary modes - - cm\ :sup:`-1` + - cm⁻¹ * - 2 - IR intensity - Only with partial charges - - km mol\ :sup:`-1` + - km·mol⁻¹ * - 2 or 3 - Force constant - Always - - mdyn Angstrom\ :sup:`-1` + - mdyn·Å⁻¹ * - 3 or 4 - Reduced mass - Always @@ -430,15 +429,15 @@ components. ---------------- One multi-frame XYZ animation named ``-.xyz`` is written per -selected mode. Each atom row contains species, x, y and z in Angstrom. The XYZ -comment records the one-based mode number, wavenumber in cm\ :sup:`-1`, frame +selected mode. Each atom row contains species, x, y and z in Å. The XYZ +comment records the one-based mode number, wavenumber in cm⁻¹, frame number and sinusoidal phase. ``modes_file`` -------------- This extended XYZ file contains one image per selected mode. The atom columns -are species, equilibrium x/y/z coordinates in Angstrom and normalized mode +are species, equilibrium x/y/z coordinates in Å and normalized mode x/y/z components. The comment declares ``Properties=species:S:1:pos:R:3:mode:R:3`` and records the one-based mode number, wavenumber and optional IR intensity. 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 e3ed1575..bfec87c7 100644 --- a/docs/source/userGuide/userGuide.rst +++ b/docs/source/userGuide/userGuide.rst @@ -1,168 +1,16 @@ +: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 - -For a file-backed periodic orthorhombic trajectory, this minimal form with -``delta_r`` alone and the default ``r_min = 0`` uses the legacy-compatible -RDF path. Coordinates are parsed directly as float64, while ``delta_r`` is -represented as float32 as it was by the legacy C input reader. Histogram -binning and all five output columns preserve the legacy arithmetic order. -Explicit ``r_max`` or ``n_bins`` values, triclinic cells, vacuum trajectories -and intra-molecular exclusion use the general PQAnalysis RDF definition. - -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 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``. - -VACF input files -^^^^^^^^^^^^^^^^ - -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`: - -.. 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 - window_start = 0.0 - window_stop = 1.0 - -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. - -Pure command line tools ------------------------ +========== -- :ref:`build_spectrum` -- :ref:`check_momentum` -- :ref:`continue_input` -- :ref:`rst2xyz` -- :ref:`traj2extxyz` -- :ref:`traj2qmcfc` -- :ref:`traj2box` +The former user-guide URL is retained for compatibility. Current documentation +is organized by task: -:ref:`check_momentum` parses file-backed velocity -trajectories directly in float64 and preserves the atom-order arithmetic of -the legacy ``equipartition.jl`` tool. This resolves conserved-momentum -residuals at the float64 noise floor instead of the former float32 parsing -floor. +* :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:`../developerGuide/developerGuide`: architecture and contribution work diff --git a/pyproject.toml b/pyproject.toml index 797b9539..772f6589 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,10 +47,11 @@ dev = [ "yapf", ] docs = [ - "sphinx>=7,<9", + "furo>=2024.8.6,<2027", + "matplotlib>=3.9,<4", + "sphinx>=8,<9", + "sphinx-copybutton>=0.5,<1", "sphinx-sitemap", - "sphinx-rtd-theme", - "breathe", "myst-parser", "better-apidoc", "six", @@ -98,4 +99,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"