Metadata-Version: 2.4
Name: mathvizpro
Version: 0.2.0
Summary: Interactive mathematical visualization library for education and exploration
Home-page: https://github.com/HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library
Author: MathViz Contributors
Author-email: HORRIDBEAST <mathviz@example.com>
License: MIT License
        
        Copyright (c) 2026 HORRIDBEAST
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library
Project-URL: Bug Tracker, https://github.com/HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library/issues
Project-URL: Source Code, https://github.com/HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library
Keywords: mathematics,visualization,education,calculus,algebra,interactive,plotting
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: sympy>=1.9.0
Requires-Dist: mplcursors>=0.5.0
Provides-Extra: jupyter
Requires-Dist: ipywidgets>=7.6.0; extra == "jupyter"
Requires-Dist: jupyter>=1.0.0; extra == "jupyter"
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0.0; extra == "test"
Requires-Dist: pytest-cov>=2.0.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# MathViz

**Interactive Mathematical Visualization Library for Python**

MathViz makes it easy to explore mathematical concepts through interactive plots, real-time parameter sliders, hover tooltips, and full Jupyter Notebook support.

---

## Features

- **Algebra Visualizer** — quadratic & polynomial explorers with live sliders (vertex, roots, discriminant)
- **Calculus Visualizer** — derivative + tangent-line visualizer; definite integral with shaded area and symbolic result
- **General-purpose tools** — multi-function plotter, parametric curves, function explorer with auto feature detection
- **Hover tooltips** via `mplcursors` — see exact x/y values and slope on hover
- **Jupyter support** — two integration layers:
  - `JupyterMathViz` — ipywidgets slider-only interface
  - `JupyterSimpleMathViz` — fully native ipywidgets (safe text input, no keyboard shortcut conflicts)
- **Widget wrappers** — thin `Slider`, `Button`, `InputBox` classes over `matplotlib.widgets`
- **Example gallery** — built-in algebra, calculus, and advanced demos
- **Save figures** — export any visualization as PNG at arbitrary DPI

---

## Installation

### From PyPI

```bash
pip install mathvizpro
```

### With Jupyter support

```bash
pip install mathvizpro[jupyter]
```

### From source (development)

```bash
git clone https://github.com/HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library.git
cd MathViz---The-Ultimate-Math-Py-Library
pip install -e .
```

### Requirements

| Package | Version |
|---|---|
| Python | ≥ 3.8 |
| numpy | ≥ 1.21.0 |
| matplotlib | ≥ 3.5.0 |
| sympy | ≥ 1.9.0 |
| mplcursors | ≥ 0.5.0 |
| ipywidgets *(optional)* | ≥ 7.6.0 |

---

## ⚠️ Install name vs import name

```bash
pip install mathvizpro      # install name on PyPI
```
```python
import mathviz              # import name in your code
from mathviz import AlgebraVisualizer, CalculusVisualizer
```

The package is published as **`mathvizpro`** on PyPI (the name `mathviz` was already taken).  
The Python import name is still **`mathviz`** — this is intentional and common (e.g. `pip install Pillow` → `import PIL`).

---

## Quick Start

```python
import mathviz
mathviz.print_info()   # version check
mathviz.quick_start()  # usage guide
```

---

## Usage

### Algebra — Quadratic Explorer

```python
from mathviz import AlgebraVisualizer
import matplotlib.pyplot as plt

viz = AlgebraVisualizer()
viz.quadratic_explorer(
    a_range=(-3, 3),
    b_range=(-5, 5),
    c_range=(-5, 5),
    x_range=(-8, 8)
)
plt.show()
```

Sliders control `a`, `b`, `c`. The vertex and roots update in real-time. Hover over the curve for exact values.

### Algebra — Polynomial Explorer

```python
viz.polynomial_explorer(degree=4, x_range=(-3, 3))
plt.show()
```

Supports degree 2–5. One slider per coefficient.

### Calculus — Derivative Visualizer

```python
from mathviz import CalculusVisualizer

calc = CalculusVisualizer()
calc.derivative_visualizer(
    func_str="x**3 - 3*x**2 + 2*x",
    x_range=(-1, 4),
    show_function_input=True   # text box to change the function
)
plt.show()
```

Shows `f(x)` and `f'(x)`. Drag the `x` slider to move the tangent line.

### Calculus — Integral Visualizer

```python
calc.integral_visualizer(
    func_str="x**2 - 4",
    x_range=(-4, 4),
    integration_range=(-2, 3)
)
plt.show()
```

Sliders `a` and `b` adjust the integration bounds. The exact symbolic result (via SymPy) is shown in the title.

### General — Multi-Function Plotter

```python
from mathviz import MathViz

core = MathViz()
core.multi_function_plotter(
    functions=["x**2", "sin(x)", "cos(x)", "2*x - 1"],
    x_range=(-5, 5)
)
plt.show()
```

Each function gets its own labeled text box. Hover tooltips show exact values.

### General — Parametric Curves

```python
import numpy as np

core.parametric_plotter(
    x_func="sin(3*t)",
    y_func="sin(2*t)",
    t_range=(0, 2 * np.pi)
)
plt.show()
```

### General — Function Explorer

```python
core.function_explorer(
    initial_func="x**4 - 2*x**2 + 1",
    x_range=(-3, 3),
    auto_detect_features=True
)
plt.show()
```

Automatically marks roots and critical points.

### Save a Figure

```python
viz = AlgebraVisualizer()
fig = viz.quadratic_explorer()
viz.save_figure("output.png", dpi=300)
```

---

## Jupyter Notebook Usage

### Important — Text Input in Notebooks

Matplotlib's native `TextBox` widget works perfectly in standalone Python scripts. Inside a Jupyter Notebook, the `%matplotlib widget` (ipympl) backend often fails to trap letter keypresses before Jupyter's own keyboard shortcuts intercept them (`x` = cut cell, `d` = delete, `b` = insert below, etc.).

**Rule of thumb:**

| Environment | Use |
|---|---|
| Standalone script / `demo.py` | `MathViz`, `AlgebraVisualizer`, `CalculusVisualizer` |
| Jupyter — sliders only | `JupyterMathViz` |
| Jupyter — text input needed | `JupyterSimpleMathViz` ✅ |

### JupyterSimpleMathViz (recommended for notebooks)

Uses native `ipywidgets.Text` boxes — all keystrokes are trapped correctly.

```python
%matplotlib inline   # or widget — both work
from mathviz import JupyterSimpleMathViz

viz = JupyterSimpleMathViz()

viz.interactive_function_plotter(initial_func="x**2")  # type sin(x), x**3, etc.
viz.interactive_derivative(initial_func="x**3")
viz.interactive_integral(initial_func="sin(x)")
viz.interactive_quadratic()
viz.interactive_parametric()

# Save the latest rendered plot even if toolbar save icon is missing:
viz.save_last_figure("my_plot.png", dpi=300)
```

### Saving in VS Code Notebooks / Colab

Some notebook frontends hide or limit the matplotlib toolbar save icon. This is
frontend behavior, not a MathViz failure.

- For `MathViz`, `AlgebraVisualizer`, `CalculusVisualizer`: use `viz.save_figure(...)`
- For `JupyterSimpleMathViz`: use `viz.save_last_figure(...)`

```python
from mathviz import AlgebraVisualizer, JupyterSimpleMathViz

# Core visualizer save
core_viz = AlgebraVisualizer()
core_viz.quadratic_explorer()
core_viz.save_figure("quadratic.png", dpi=300)

# JupyterSimple save
simple_viz = JupyterSimpleMathViz()
simple_viz.interactive_function_plotter("sin(x)")
simple_viz.save_last_figure("function.png", dpi=300)
```

### JupyterMathViz (slider-only fallback)

```python
from mathviz import JupyterMathViz

jv = JupyterMathViz()
jv.interactive_quadratic()
```

---

## Example Gallery

```python
from mathviz import ExampleGallery

gallery = ExampleGallery()

gallery.algebra_examples()    # quadratic & polynomial demos
gallery.calculus_examples()   # derivative & integral demos
gallery.advanced_examples()   # parametric, multi-function demos

# List all available examples
for category, items in gallery.get_example_list().items():
    print(f"{category}: {items}")
```

---

## Supported Function Syntax

All text inputs accept standard SymPy / NumPy expressions:

| Math | Python syntax |
|---|---|
| x² | `x**2` |
| sin x | `sin(x)` |
| eˣ | `exp(x)` |
| ln x | `log(x)` |
| √x | `sqrt(x)` |
| \|x\| | `Abs(x)` |
| π | `pi` |

---

## Project Structure

```
mathviz/
├── __init__.py           # Public API, get_info(), print_info(), quick_start()
├── core.py               # MathViz base class — all general-purpose tools
├── concepts.py           # AlgebraVisualizer, CalculusVisualizer
├── widgets.py            # Slider, Button, InputBox wrappers
├── examples.py           # ExampleGallery
├── jupyter_integration.py# JupyterMathViz (ipywidgets.interact, sliders only)
├── jupyter_simple.py     # JupyterSimpleMathViz (ipywidgets.Text, full input)
└── utils.py              # export_to_data_url and helpers

notebooks/
├── getting_started.ipynb # Full walkthrough — run this first
├── algebra_examples.ipynb
├── calculus_examples.ipynb
└── test_mathviz.ipynb    # Manual integration test notebook

tests/
├── test_core.py          # 45 tests — MathViz base class
├── test_algebra.py       # 38 tests — AlgebraVisualizer
├── test_calculus.py      # 37 tests — CalculusVisualizer
└── test_integration.py   # 37 tests — package metadata, widgets, utils, gallery
```

---

## Running Tests

```bash
# All tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=mathviz --cov-report=term-missing

# Quick smoke test
pytest test_mathviz.py -v
```

Current status: **172 tests, 0 failures**.

---

## Architecture

```
MathViz (core.py)
├── create_figure() / show() / close() / save_figure()
├── add_slider() / add_button() / add_textbox()
├── function_explorer()
├── multi_function_plotter()
└── parametric_plotter()

AlgebraVisualizer(MathViz)       — concepts.py
├── quadratic_explorer()
└── polynomial_explorer()

CalculusVisualizer(MathViz)      — concepts.py
├── derivative_visualizer()
└── integral_visualizer()

JupyterSimpleMathViz             — jupyter_simple.py (standalone, no MathViz inheritance)
├── interactive_function_plotter()
├── interactive_derivative()
├── interactive_integral()
├── interactive_quadratic()
└── interactive_parametric()
```

Key design decisions:
- All visualizer methods return `self.fig` — composable and testable
- Invalid function strings display an error inside the axes; they never raise to the caller
- Widgets are stored in `self.widgets[label]` so Python's GC cannot destroy them mid-session
- `mplcursors` and `ipywidgets` are optional — guarded by `try/except ImportError`
- SymPy handles symbolic differentiation and integration; `lambdify` converts to NumPy for plotting

---

## Known Limitations

- Matplotlib `TextBox` in Jupyter Notebooks intercepts letter keypresses → use `JupyterSimpleMathViz` instead
- `JupyterSimpleMathViz` redraws the full figure on every widget change (ipywidgets constraint) — hover tooltips not available
- `polynomial_explorer` supports degree 2–5 only; degree outside this range raises `ValueError`
- Very large x-ranges with discontinuous functions (e.g. `tan(x)`) may show visual spikes

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Run tests: `pytest tests/`
4. Submit a pull request to [HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library](https://github.com/HORRIDBEAST/MathViz---The-Ultimate-Math-Py-Library)

Please ensure all existing tests pass and add tests for new functionality.
