ParSub - Agentic Math/Physics Research Tool

ParSub reads the mathematics in a LaTeX document, works out what can be computed from it, and writes a ready-to-run Python script that evaluates, plots, solves, optimizes, integrates, differentiates or numerically verifies every formula it understands — producing publication-quality plots and data files.

paper.tex ──parse──► expressions ──analyze──► tasks ──generate──► generated_computation.py ──run──► plots/ + data/

🔬 Features

• LaTeX parsing – extracts inline ($...$, \(...\)) and display math ($$...$$, \[...\], equation, align, gather, multline, eqnarray, ...), splits multi-line environments, keeps equation labels, skips the preamble, comments and bibliography.
• LaTeX → SymPy – uses SymPy's LaTeX parser in strict mode (no silently truncated formulas) with clean-up for real papers: \pi, e^{x}, \Gamma(z), subscripts such as v_0/x_{max}, font macros, :=, and side conditions such as (\Re(z) > 0) that become sampling constraints.
• Special-function notation – hypergeometric functions {}_pF_q(a; b; z), Pochhammer symbols (a)_n, Laguerre/Gegenbauer/Jacobi polynomials L_n^{(a)}(x), Bessel functions J_\nu(x), indexed functions w_{\alpha}(z) and derivatives w''(z), w^{\prime}(z).
• Uses the document's own definitions – a function defined in the paper (\pi(x) = 1/\Gamma(x+1)) is substituted wherever it is used, parameters defined in terms of others (\vartheta = \alpha + (b+1)/2) get consistent values, and i = \sqrt{-1} is honoured.
• Checks the mathematics – identities, alternative definitions of the same function and differential equations are verified numerically, so misprints are caught (see Validation).
• Goal recognition – reads the surrounding prose ("we want to plot", "find the maximum", "solve for x", ...) to choose between evaluate, plot, solve, optimize, integrate, differentiate, series, spectral (windowed Fourier amplitude spectrum), verify (numerical check of identities) and symbolic.
• Parameter inference – decides which variables are swept and which are held fixed, with sensible ranges and default values; values stated in the text (e.g. $g = 9.81$) are used automatically.
• Self-contained code generation – one small, editable function per task plus an embedded helper library (NumPy, SciPy, SymPy, Matplotlib, pandas). Integrals and infinite sums are evaluated numerically when no closed form is needed.
• Robust execution – tasks are isolated and errors are recorded in summary.json; execution is unlimited by default, with optional overall and per-task time limits.
• High-quality output – color-cycled plots with concise mathematical legends, 400 DPI PNG output, and CSV/TSV/Excel/JSON data.
• Conference poster source – each manuscript analysis also creates an editable, one-page A0 portrait generated_poster.tex with author metadata, selected equations, analysis summaries, and embedded model curves when a parsed expression can be sampled safely.
• Privacy-first – everything runs locally; no data leaves your machine.
• CLI, Python API, REST API and Docker image, covered by an automated test suite.

📦 Installation

Requires Python 3.9 or newer.

pip install parsub

Optional scientific libraries for custom Python extensions can be installed with:

pip install "parsub[science]"

This extra installs Xarray, Astropy, NetworkX, GeoPandas, QuTiP, Uproot and TensorNetwork; it does not add automatic LaTeX adapters for those libraries. Kwant, PyDSTool and SageMath need separate platform-specific installations.

From source (for development):

git clone https://github.com/PSubrat29/parsub.git
cd parsub
pip install -e ".[dev]"     # includes the test tools

🚀 Quick Start

Command line

# Try the built-in projectile-motion demo (analyze + run)
parsub demo --run

# Analyze a LaTeX file, then run the generated code
parsub analyze examples/projectile.tex --output-dir ./results
parsub run ./results/generated_computation.py

# ...or both in one step
parsub analyze examples/sample.tex -o ./results --run

parsub analyze writes generated_poster.tex alongside the analysis and computation outputs. Compile it with a LaTeX distribution, for example:

pdflatex -interaction=nonstopmode -halt-on-error generated_poster.tex

Review scientific content, source metadata, and conference requirements before presenting it.

parsub --help lists all commands and options (analyze, run, demo, version).

Python API

import parsub

# One call: parse, analyze, and write the computation script, analysis, and A0 poster TeX
result = parsub.analyze_latex(r"We plot $y = \sin(x) e^{-x/5}$", output_dir="./output")
print(result.poster_path)
for task in result.tasks:
    print(task["goal_type"], "-", task["description"])

# Run the generated script (results go next to it: ./output/plots and ./output/data)
process = parsub.run_generated_code(result.code_path)
print(process.stdout)

The individual stages are available too:

from parsub.parser.latex_parser import parse_latex_source
from parsub.analyzer.expression_analyzer import analyze_expressions
from parsub.generator.code_generator import generate_code_from_tasks

parsed = parse_latex_source(open("paper.tex", encoding="utf-8").read())
tasks = analyze_expressions(parsed["expressions"], {
    "goals": parsed["goals"],
    "methods": parsed["methods"],
    "assignments": parsed["assignments"],
})
code_file = generate_code_from_tasks(tasks, "./output")

REST API

parsub-api                                   # http://127.0.0.1:8000 (interactive docs at /docs)
# or: uvicorn parsub.api.main:app --host 0.0.0.0 --port 8000

curl -X POST http://127.0.0.1:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"latex_source": "\\begin{equation} E = mc^2 \\end{equation}", "output_dir": "api_results"}'

curl -X POST http://127.0.0.1:8000/run \
  -H "Content-Type: application/json" \
  -d '{"code_path": "api_results/generated_computation.py"}'

Endpoints: POST /analyze, POST /upload, POST /run, GET /execute/{path}, GET /download/{path}, GET /health. All files live inside one output root (PARSUB_OUTPUT_ROOT, default ./output); paths outside it are rejected.

Docker

The REST API is available as a ready-made image (no Python installation needed):

docker run -d --name parsub -p 8000:8000 -v parsub-data:/data ghcr.io/psubrat29/parsub:latest

Open http://localhost:8000/ for the interactive API documentation. Image tags, Docker Compose, configuration and where results are kept are described on the Docker page.

📊 Output

output/
├── generated_computation.py     # the generated, editable Python script
├── analysis.json                # what was extracted and why each task was chosen
├── plots/
│   ├── task_1_plot.png          # 1-D plots
│   ├── task_2_surface_plot.png  # 2-D surface plots
│   └── task_3_verification_plot.png
└── data/
    ├── task_1_plot_data.csv     # numerical data
    ├── task_3_verification.json # results (roots, extrema, integrals, identity checks, ...)
    └── summary.json             # status of every task

The generated script accepts --output-dir DIR, --timeout SECONDS (per task; unlimited by default) and --tasks 1,3.

The parser has no 30,000-word limit. REST uploads are limited to 5 MB; local files are limited by available memory. Domain libraries such as Xarray, Astropy, NetworkX, GeoPandas, QuTiP, Kwant, Uproot, PyDSTool, SageMath and TensorNetwork are not automatically wired into ParSub's LaTeX-to-computation pipeline; see the user guide for platform and customization notes. Generated figures are styled for clarity, but still require scientific validation and journal-specific review.

📚 Documentation

• User Guide – detailed usage of the CLI, Python API and REST API
• Docker image – the REST API as a ready-made container
• API Reference – modules, functions and data formats
• Development Guide – setting up, testing, releasing
• Validation report – what ParSub found in the example paper
• Changelog – what changed in each version
• Examples – projectile.tex (physics) and sample.tex (a research note on generalized Bessel functions)

✅ Validation on a real paper

examples/sample.tex is a research note on generalized Bessel functions with 25 numbered equations. Running

parsub analyze examples/sample.tex -o results --run

converts every numbered equation except the generic definition (4) and runs 28 computations in about 90 seconds. Of the 22 numerical checks, 19 confirm the paper's identities. Among them: the Gamma integral, both Beta-function forms, Kummer's second transformation, the claim that the series (9) solves the differential equation (8), and every alternative form of w_α(z) and of the Bessel-Clifford function. The remaining three flag real problems:

Equation	ParSub's verdict	Explanation
(6)	does not hold	Kummer's first formula is misprinted; it should read ₁F₁(ε; ϱ; z) = eᶻ ₁F₁(ϱ−ε; ϱ; −z)
(22)	does not hold	the Laguerre index should be L_k^{(ϑ)}, not L_k^{(ϑ−1)} (equation (23) is correct)
w_α(0) = 0	holds except at α = 0	true for Re α > 0 only

Each finding was confirmed independently with mpmath. Details are in the validation report.

🧪 Running Tests

pip install -e ".[dev]"
pytest                      # all tests
pytest --cov=parsub         # with coverage
pytest tests/test_parser.py # one module

🔒 Privacy & Security

• Local processing – parsing, analysis, code generation and execution happen on your machine.
• No telemetry – nothing is sent to external servers.
• Isolated execution – generated code runs in a separate Python process; optional time limits can be set explicitly. It is ordinary Python, so review it before running code generated from documents you do not trust.
• File access control – the REST API only reads and writes inside its output root and only runs scripts that ParSub generated there.

🛠️ Architecture

src/parsub/
├── parser/      # LaTeX walking (pylatexenc) and LaTeX → SymPy conversion
├── analyzer/    # goal detection, variable roles, sampling strategy
├── generator/   # code generation + runtime helpers embedded in generated scripts
├── core/        # shared parameter knowledge and the end-to-end pipeline
├── cli/         # `parsub` command (Typer + Rich)
└── api/         # REST API (FastAPI)

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md.

📄 License

ParSub is released under the MIT License. See LICENSE.

🙏 Acknowledgements

• SymPy for symbolic mathematics and LaTeX parsing
• pylatexenc for LaTeX tokenisation
• NumPy, SciPy, pandas and Matplotlib for numerics, data and plotting
• Typer and Rich for the CLI
• FastAPI for the REST API

---

ParSub - Turning LaTeX mathematics into computational insights, automatically.