feat: add vibrational analysis workflow

[galjos]

Summary

• add vibrational analysis API and vibrations CLI
• write tabular results, normal modes, per-mode XYZ, and ASE/Jmol extended XYZ modes
• add full feature coverage tests, examples, user docs, and API docs

Closes #134
Related: MolarVerse/PQ#277

Checks

• python -m pytest -o addopts='' --cov=PQAnalysis.analysis.vibrational --cov=PQAnalysis.cli.vibrations --cov-report=term-missing tests/analysis/vibrational tests/cli/test_vibrations.py (100%)
• bash pytest.sh
• python -m yapf --diff tests/analysis/vibrational/test_vibrational_analysis.py tests/analysis/vibrational/test_api.py tests/analysis/vibrational/test_vibrational_input_file_reader.py tests/cli/test_vibrations.py
• python -m sphinx -b html source /tmp/pqanalysis-docs-pr-check
• PQ-to-PQAnalysis example, ASE read check, and Jmol render check

---

↩️ Re-creates #146, which GitHub auto-closed and made un-reopenable after the feature/vibrational-analysis branch was force-pushed during a history rewrite (removal of a codex branch name from a merge-commit message). The branch was rebased cleanly onto dev; see #146 for prior review discussion.

[github-actions]

PYLINT REPORT

Your code has been rated at 9.80/10

Full report

Raw metrics

type	number	%	previous	difference
code	9956	42.92	NC	NC
docstring	9438	40.68	NC	NC
comment	273	1.18	NC	NC
empty	3532	15.22	NC	NC

Duplication

	now	previous	difference
nb duplicated lines	0	NC	NC
percent duplicated lines	0.000	NC	NC

Messages by category

type	number	previous	difference
convention	5	NC	NC
refactor	71	NC	NC
warning	15	NC	NC
error	5	NC	NC

% errors / warnings by module

module	error	warning	refactor	convention
PQAnalysis.type_checking	40.00	0.00	0.00	0.00
PQAnalysis.atomic_system.atomic_system	20.00	13.33	12.68	0.00
PQAnalysis.analysis.vibrational.vibrational_analysis	20.00	0.00	14.08	0.00
PQAnalysis	20.00	0.00	0.00	0.00
PQAnalysis.topology.init	0.00	13.33	0.00	0.00
PQAnalysis.tools.traj_to_com_traj	0.00	13.33	0.00	0.00
PQAnalysis.io.traj_file._process_lines_py	0.00	13.33	0.00	0.00
PQAnalysis.io.moldescriptor_reader	0.00	13.33	0.00	0.00
PQAnalysis.tools.add_molecule	0.00	6.67	12.68	0.00
PQAnalysis.io.conversion_api	0.00	6.67	2.82	0.00
PQAnalysis.version	0.00	6.67	0.00	0.00
PQAnalysis.utils.custom_logging	0.00	6.67	0.00	0.00
PQAnalysis.io.write_api	0.00	6.67	0.00	0.00
PQAnalysis.io.nep.nep_writer	0.00	0.00	9.86	20.00
PQAnalysis.io.traj_file.trajectory_reader	0.00	0.00	5.63	0.00
PQAnalysis.topology.bonded_topology.dihedral	0.00	0.00	4.23	0.00
PQAnalysis.core.residue	0.00	0.00	4.23	0.00
PQAnalysis.analysis.rdf.rdf	0.00	0.00	4.23	0.00
PQAnalysis.topology.bonded_topology.bonded_topology	0.00	0.00	2.82	0.00
PQAnalysis.topology.bonded_topology.bond	0.00	0.00	2.82	0.00
PQAnalysis.topology.bonded_topology.angle	0.00	0.00	2.82	0.00
PQAnalysis.core.cell.cell	0.00	0.00	2.82	0.00
PQAnalysis.atomic_system._standard_properties	0.00	0.00	2.82	0.00
PQAnalysis.analysis.vibrational.vibrational_input_file_reader	0.00	0.00	1.41	20.00
PQAnalysis.traj.formats	0.00	0.00	1.41	0.00
PQAnalysis.topology.topology	0.00	0.00	1.41	0.00
PQAnalysis.topology.selection	0.00	0.00	1.41	0.00
PQAnalysis.io.traj_file.frame_reader	0.00	0.00	1.41	0.00
PQAnalysis.io.restart_file.restart_reader	0.00	0.00	1.41	0.00
PQAnalysis.io.input_file_reader.pq_analysis._parse	0.00	0.00	1.41	0.00
PQAnalysis.io.input_file_reader.pq.pq_input_file_reader	0.00	0.00	1.41	0.00
PQAnalysis.io.input_file_reader.input_file_parser	0.00	0.00	1.41	0.00
PQAnalysis.io.info_file_reader	0.00	0.00	1.41	0.00
PQAnalysis.io.formats	0.00	0.00	1.41	0.00
PQAnalysis.core.atom.element	0.00	0.00	0.00	40.00
PQAnalysis.analysis.rdf.rdf_input_file_reader	0.00	0.00	0.00	20.00

Messages

message id	occurrences
too-many-positional-arguments	17
too-many-arguments	17
too-many-instance-attributes	10
fixme	9
inconsistent-return-statements	8
too-many-locals	6
invalid-name	4
too-many-return-statements	3
too-complex	3
duplicate-code	3
unused-import	2
too-many-branches	2
redefined-builtin	2
missing-kwoa	2
unexpected-keyword-arg	1
too-many-statements	1
too-many-public-methods	1
too-many-lines	1
possibly-used-before-assignment	1
no-member	1
missing-param-doc	1
arguments-differ	1

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.20%. Comparing base (f8c15f6) to head (5a3e82e).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #150      +/-   ##
==========================================
+ Coverage   90.41%   91.20%   +0.79%     
==========================================
  Files         130      136       +6     
  Lines        5685     6188     +503     
==========================================
+ Hits         5140     5644     +504     
+ Misses        545      544       -1     

Flag	Coverage Δ
unittests	91.20% <100.00%> (+0.79%)	⬆️

Files with missing lines	Coverage Δ
PQAnalysis/analysis/__init__.py	100.00% <100.00%> (ø)
PQAnalysis/analysis/vibrational/__init__.py	100.00% <100.00%> (ø)
PQAnalysis/analysis/vibrational/api.py	100.00% <100.00%> (ø)
PQAnalysis/analysis/vibrational/exceptions.py	100.00% <100.00%> (ø)
...lysis/analysis/vibrational/vibrational_analysis.py	100.00% <100.00%> (ø)
...lysis/vibrational/vibrational_input_file_reader.py	100.00% <100.00%> (ø)
PQAnalysis/cli/main.py	96.77% <100.00%> (+0.10%)	⬆️
PQAnalysis/cli/vibrations.py	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.