marksfuncs 0.2__tar.gz → 1.1__tar.gz

{marksfuncs-0.2 → marksfuncs-1.1}/LICENSE.txt

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 mark.
-
-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.
+MIT License
+
+Copyright (c) 2024 mark.
+
+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.

marksfuncs-1.1/PKG-INFO

@@ -0,0 +1,501 @@
+Metadata-Version: 2.4
+Name: marksfuncs
+Version: 1.1
+Summary: Graph many mathematical functions
+Home-page: https://github.com/marc1fino/marksfuncs
+Author: mark. (Marc Pérez)
+Author-email: <marcperezcarrasco2010@gmail.com>
+License: MIT
+Keywords: python,maths,graphics,functions,xy,mathematical functions
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# marksfuncs
+
+A comprehensive mathematical function plotting library for Python with **50+ built-in function classes**, **free-form expression evaluation**, and **publication-quality graphs**.
+
+The project provides ready-to-use classes for elementary functions (linear, quadratic, exponential), transcendental functions (trigonometric, hyperbolic, logarithmic), special functions (Bessel, Gamma, Error, Airy), probability distributions (Gaussian, Weibull, Beta, Gamma, Poisson), and a powerful free-form expression evaluator that works like GeoGebra — all with clean APIs for both interactive plotting and programmatic image generation.
+
+**Python** | **Mathematics** | **Data Visualization** | **Scientific Computing**
+
+![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
+![Dependencies](https://img.shields.io/badge/Dependencies-NumPy%2C%20SciPy%2C%20Matplotlib-blue?style=flat-square)
+
+## Features
+
+- **50+ function classes** — from elementary to special functions and probability distributions
+- **Free-form expressions** — `ExpressionFunction` evaluates any mathematical string (like GeoGebra)
+- **Polynomial by coefficients** — `PolynomialCoefficients` defines polynomials via degree→coefficient mapping
+- **Dual output modes** — `graph()` for interactive display, `image()` for programmatic PNG buffers
+- **Customizable ranges** — configurable x-range (start, end, points) and optional y-axis limits
+- **Rich label support** — automatic formula labels on every plot
+- **Publication ready** — high-quality Matplotlib output with grid, legend, and axis labels
+- **Zero-config** — works out of the box with sensible defaults
+
+## Function Categories
+
+### Elementary Functions
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `Identity` | f(x) = x | `x_values_list` |
+| `Linear` | f(x) = mx + b | `m`, `b`, `x_values_list` |
+| `Quadratic` | f(x) = ax² + bx + c | `a`, `b`, `c`, `x_values_list`, `y_values?` |
+| `Polynomial` | f(x) = Σ aᵢxⁱ (from string) | `polynomial_str`, `x_values_list`, `y_values?` |
+| `PolynomialCoefficients` | f(x) = Σ aᵢxⁱ (from dict/list) | `coefficients`, `x_values_list`, `y_values?` |
+| `Power` | f(x) = axᵇ | `a`, `b`, `x_values_list`, `y_values?` |
+| `Root` / `Radical` | f(x) = a√(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+| `Absolute` | f(x) = a\|bx\| | `a`, `b`, `x_values_list`, `y_values?` |
+
+### Exponential & Logarithmic
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `Exponential` | f(x) = a·eᵇˣ | `a`, `b`, `x_values_list`, `y_values?` |
+| `Logarithmic` | f(x) = a·log(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+| `GeneralizedExponential` | f(x) = a·e^(-(x-b)²/2c²) | `a`, `b`, `c`, `x_values_list` |
+| `ComplexExponential` | f(x) = a·e^(jbx) | `a`, `b`, `x_values_list` |
+
+### Trigonometric & Hyperbolic
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `Trigonometric` | f(x) = a·sin(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+| `Hyperbolic` | f(x) = a·sinh(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+| `HyperbolicTangent` | f(x) = a·tanh(x) | `a`, `x_values_list`, `y_values?` |
+| `InverseTrigonometric` | f(x) = a·arcsin(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+| `SincDirichlet` | f(x) = sinc(ax) | `a`, `x_values_list`, `y_values?` |
+| `Dirichlet` | f(x) = sinc(ax - b) | `a`, `b`, `x_values_list`, `y_values?` |
+
+### Special Functions
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `BesselOrder0` | f(x) = J₀(x) | `x_values_list`, `y_values?` |
+| `BesselOrder1` | f(x) = J₁(x) | `x_values_list`, `y_values?` |
+| `Error` | f(x) = erf(x) | `x_values_list`, `y_values?` |
+| `Airy` | f(x) = Ai(x) | `x_values_list`, `y_values?` |
+| `SineFresnel` | f(x) = S(x) | `x_values_list`, `y_values?` |
+| `CosineFresnel` | f(x) = C(x) | `x_values_list`, `y_values?` |
+| `LogGamma` | f(x) = ln(Γ(x)) | `x_values_list`, `y_values?` |
+| `LogSineProduct` | f(x) = log\|sin(x)\| | `x_values_list` |
+
+### Sigmoid & Activation Functions
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `Sigmoid` | f(x) = a/(1+e^(-b(x-c))) | `a`, `b`, `c`, `x_values_list`, `y_values?` |
+| `Logistic` | f(x) = c/(1+e^(-b(x-a))) | `a`, `b`, `c`, `x_values_list` |
+| `GeneralizedLogistics` | f(x) = d/(1+e^(-b(x-a)))+c | `a`, `b`, `c`, `d`, `x_values_list` |
+| `Gompertz` | f(x) = a·e^(-b·e^(-cx)) | `a`, `b`, `c`, `x_values_list`, `y_values?` |
+| `Hill` | f(x) = Vₘₐₓ·xⁿ/(Kⁿ+xⁿ) | `vmax`, `k`, `n`, `x_values_list`, `y_values?` |
+
+### Probability Distributions
+
+| Class | Distribution | Parameters |
+| :--- | :--- | :--- |
+| `Gaussian` / `Gauss` | Normal (μ, σ) | `mu`, `sigma` / `a`, `b`, `c`, `x_values_list`, `y_values?` |
+| `Weibull` | Weibull (k, λ) | `k`, `lambda_param`, `x_values_list`, `y_values?` |
+| `Beta` | Beta (α, β) | `alpha`, `beta`, `x_values_list`, `y_values?` |
+| `Gamma` | Gamma (k, θ) | `k`, `theta`, `x_values_list`, `y_values?` |
+| `Poisson` | Poisson (λ) | `lambda_param`, `x_values_list`, `y_values?` |
+| `ChiSquare` | χ² (df) | `df`, `x_values_list`, `y_values?` |
+
+### Waveforms & Periodic Functions
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `SawTooth` | f(x) = a(x - 2π⌊x/2π⌋) | `a`, `b`, `x_values_list`, `y_values?` |
+| `SquareWave` | f(x) = a(1-2⌊x/2π⌋%2) | `a`, `b`, `x_values_list`, `y_values?` |
+| `Sign` | f(x) = sign(x) | `x_values_list`, `y_values?` |
+| `Floor` | f(x) = ⌊x⌋ | `x_values_list` |
+| `Ceil` | f(x) = ⌈x⌉ | `x_values_list` |
+| `Triangular` | f(x) = max(0, a - \|x-b\|/c) | `a`, `b`, `c`, `x_values_list`, `y_values?` |
+
+### Step & Impulse Functions
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `UnitStep` | f(x) = a·u(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+| `Heaviside` | f(x) = u(x) | `x_values_list`, `y_values?` |
+| `DiracDelta` | f(x) = δ(x) | `x_values_list` |
+| `TopHat` | f(x) = 1 for x∈[a,b] | `a`, `b`, `x_values_list` |
+
+### Rational & Algebraic
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `Rational` | f(x) = a/(bx) | `a`, `b`, `x_values_list`, `y_values?` |
+
+### Physics & Engineering
+
+| Class | Formula | Parameters |
+| :--- | :--- | :--- |
+| `Planck` | Blackbody radiation | `h`, `k`, `c`, `T`, `x_values_list`, `y_values?` |
+
+### Number-Theoretic & Recursive
+
+| Class | Description | Parameters |
+| :--- | :--- | :--- |
+| `Ackermann` | Ackermann function (scatter) | `m`, `n`, `x_values_list` |
+| `ModifiedAckermann` | Modified Ackermann (m=0..3) | `m`, `n`, `x_values_list` |
+| `Fibonacci` | Fibonacci sequence (scatter) | `n`, `x_values_list` |
+| `Legendre` | Legendre polynomial Pₙ(x) | `grade`, `x_values_list` |
+
+### Free-Form Expression Evaluator
+
+| Class | Description | Parameters |
+| :--- | :--- | :--- |
+| `ExpressionFunction` | Evaluate any math expression string | `expression`, `x_values_list`, `y_values?`, `variable='x'` |
+
+## Quick Start
+
+```bash
+pip install marksfuncs
+```
+
+```python
+from marksfuncs import Exponential, Linear, PolynomialCoefficients, ExpressionFunction
+from PIL import Image
+
+# 1. Interactive plotting
+Exponential(a=4, b=2, x_values_list=[-5, 5, 100]).graph()
+
+# 2. With custom y-axis limits
+Exponential(a=4, b=2, x_values_list=[-5, 5, 100], y_values=(-10, 10)).graph()
+
+# 3. Programmatic image generation (PNG buffer)
+img_buffer = Linear(m=3, b=5, x_values_list=[-5, 5, 100]).image()
+img = Image.open(img_buffer)
+img.save("linear.png")
+
+# 4. Polynomial by coefficients (degree → coefficient)
+# f(x) = 3x² + 2x + 1
+poly = PolynomialCoefficients(
+    coefficients={0: 1, 1: 2, 2: 3},  # or [1, 2, 3]
+    x_values_list=[-5, 5, 100]
+)
+poly.graph()
+
+# 5. Free-form expressions like GeoGebra!
+expr = ExpressionFunction(
+    expression="sin(x) + x**2",
+    x_values_list=[-5, 5, 100]
+)
+expr.graph()
+
+# Custom variable name
+expr2 = ExpressionFunction(
+    expression="exp(-t)*cos(t)",
+    x_values_list=[0, 10, 200],
+    variable='t'
+)
+expr2.graph()
+
+# Advanced: special functions
+expr3 = ExpressionFunction(
+    expression="erf(x) + gamma(x+1)",
+    x_values_list=[0.1, 5, 100]
+)
+expr3.graph()
+```
+
+## Installation
+
+```bash
+# From PyPI (when published)
+pip install marksfuncs
+
+# From source
+git clone https://github.com/marc1fino/marksfuncs.git
+cd marksfuncs
+pip install -e .
+```
+
+Requires **Python 3.8+**. Dependencies: `numpy`, `scipy`, `matplotlib`, `pillow`.
+
+## Core API
+
+### Common Parameters
+
+All classes share these parameters:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `x_values_list` | `[float, float, int]` | **Required.** `[x_min, x_max, num_points]` — defines the x-axis sampling range |
+| `y_values` | `(float, float)` | **Optional.** `(y_min, y_max)` — sets fixed y-axis limits for consistent scaling |
+
+### Core Methods
+
+Every class provides:
+
+| Method | Returns | Description |
+| :--- | :--- | :--- |
+| `graph()` | `None` | Displays interactive Matplotlib window with the plot |
+| `image()` | `io.BytesIO` | Returns PNG image buffer for programmatic use (save, embed, serve) |
+
+### ExpressionFunction Namespace
+
+`ExpressionFunction` provides a safe evaluation context with:
+
+- **Constants**: `pi`, `e`, `inf`, `nan`
+- **NumPy functions**: `sin`, `cos`, `tan`, `arcsin`, `arccos`, `arctan`, `sinh`, `cosh`, `tanh`, `exp`, `log`, `log10`, `log2`, `sqrt`, `cbrt`, `abs`, `floor`, `ceil`, `round`, `sign`, `heaviside`, `maximum`, `minimum`, `clip`, `power`, `mod`, `sinc`, `deg2rad`, `rad2deg`
+- **SciPy special**: `erf`, `erfc`, `gamma`, `gammaln`, `beta`, `betaln`, `j0`, `j1`, `jn`, `yn`, `airy`
+
+## Examples
+
+### Basic Elementary Functions
+
+```python
+from marksfuncs import Linear, Quadratic, Power, Absolute
+
+# Linear: f(x) = 2x + 3
+Linear(m=2, b=3, x_values_list=[-10, 10, 200]).graph()
+
+# Quadratic: f(x) = x² - 4x + 4
+Quadratic(a=1, b=-4, c=4, x_values_list=[-2, 6, 200]).graph()
+
+# Power: f(x) = 2x³
+Power(a=2, b=3, x_values_list=[-3, 3, 200]).graph()
+
+# Absolute value: f(x) = |x - 2|
+Absolute(a=1, b=1, x_values_list=[-5, 5, 200]).graph()
+```
+
+### Example: Trigonometric & Hyperbolic
+
+```python
+from marksfuncs import Trigonometric, Hyperbolic, HyperbolicTangent
+
+# Sine wave: f(x) = 3sin(2x)
+Trigonometric(a=3, b=2, x_values_list=[-2*3.14, 2*3.14, 400]).graph()
+
+# Hyperbolic sine: f(x) = 2sinh(x)
+Hyperbolic(a=2, b=1, x_values_list=[-3, 3, 200]).graph()
+
+# Tanh activation: f(x) = tanh(x)
+HyperbolicTangent(a=1, x_values_list=[-5, 5, 200]).graph()
+```
+
+### Example: Probability Distributions
+
+```python
+from marksfuncs import Gaussian, Weibull, Beta, Gamma, Poisson, ChiSquare
+
+# Normal distribution: μ=0, σ=1
+Gaussian(mu=0, sigma=1, x_values_list=[-4, 4, 400]).graph()
+
+# Weibull: k=2, λ=1.5
+Weibull(k=2, lambda_param=1.5, x_values_list=[0, 5, 400]).graph()
+
+# Beta: α=2, β=5
+Beta(alpha=2, beta=5, x_values_list=[0, 1, 400]).graph()
+
+# Chi-square: df=3
+ChiSquare(df=3, x_values_list=[0, 10, 400]).graph()
+```
+
+### Example: Special Functions
+
+```python
+from marksfuncs import BesselOrder0, BesselOrder1, Error, Airy, LogGamma
+
+# Bessel J₀
+BesselOrder0(x_values_list=[0, 20, 400]).graph()
+
+# Error function
+Error(x_values_list=[-3, 3, 400]).graph()
+
+# Airy Ai(x)
+Airy(x_values_list=[-10, 10, 400]).graph()
+
+# Log Gamma
+LogGamma(x_values_list=[0.1, 5, 400]).graph()
+```
+
+### Free-Form Expressions (GeoGebra-like)
+
+```python
+from marksfuncs import ExpressionFunction
+
+# Any valid mathematical expression
+ExpressionFunction(
+    expression="sin(x)*exp(-x/5)",
+    x_values_list=[0, 20, 400]
+).graph()
+
+# Multiple terms
+ExpressionFunction(
+    expression="x**3 - 3*x**2 + 2*x - 1",
+    x_values_list=[-2, 4, 400]
+).graph()
+
+# With special functions
+ExpressionFunction(
+    expression="erf(x) + sin(x**2)/2",
+    x_values_list=[-3, 3, 400]
+).graph()
+
+# Custom variable
+ExpressionFunction(
+    expression="cos(omega*t)*exp(-t/tau)",
+    x_values_list=[0, 10, 400],
+    variable='t'
+).graph()
+
+# Polar-like: r = 1 + cos(theta)
+ExpressionFunction(
+    expression="1 + cos(x)",
+    x_values_list=[0, 2*3.14159, 400]
+).graph()
+```
+
+### Polynomial by Coefficients
+
+```python
+from marksfuncs import PolynomialCoefficients
+
+# f(x) = 4x⁴ - 3x³ + 2x² - x + 5
+# Using dict (degree → coefficient)
+poly1 = PolynomialCoefficients(
+    coefficients={0: 5, 1: -1, 2: 2, 3: -3, 4: 4},
+    x_values_list=[-2, 2, 400]
+)
+poly1.graph()
+
+# Using list (index = degree)
+poly2 = PolynomialCoefficients(
+    coefficients=[5, -1, 2, -3, 4],
+    x_values_list=[-2, 2, 400]
+)
+poly2.graph()
+
+# Sparse polynomial: f(x) = x¹⁰ - 1
+poly3 = PolynomialCoefficients(
+    coefficients={0: -1, 10: 1},
+    x_values_list=[-1.5, 1.5, 400]
+)
+poly3.graph()
+```
+
+### Image Generation for Web/Apps
+
+```python
+from marksfuncs import Sigmoid, ExpressionFunction
+from PIL import Image
+import io
+
+# Generate PNG for embedding
+buf = Sigmoid(a=1, b=1, c=0, x_values_list=[-10, 10, 400]).image()
+
+# Save to file
+with open("sigmoid.png", "wb") as f:
+    f.write(buf.getvalue())
+
+# Or open directly
+img = Image.open(buf)
+img.show()
+
+# Expression function to image
+buf2 = ExpressionFunction(
+    expression="1/(1+exp(-x))",
+    x_values_list=[-10, 10, 400]
+).image()
+```
+
+## Project Structure
+
+```text
+marksfuncs/
+├── marksfuncs/
+│   ├── __init__.py          # Exports all 50+ classes
+│   └── functions.py         # All function implementations
+├── setup.py                 # Packaging configuration
+├── README.md                # This file
+└── LICENSE                  # MIT License
+```
+
+## Requirements
+
+- **Python 3.8+**
+- `numpy` ≥ 1.21
+- `scipy` ≥ 1.7
+- `matplotlib` ≥ 3.5
+- `pillow` ≥ 9.0
+
+## Development
+
+```bash
+git clone https://github.com/marc1fino/marksfuncs.git
+cd marksfuncs
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
+pip install -e .
+
+# Quick smoke test
+python -c "
+from marksfuncs import Linear, ExpressionFunction, PolynomialCoefficients
+import numpy as np
+
+# Test Linear
+assert Linear(m=2, b=3, x_values_list=[0, 1, 2])._evaluate(5) == 13
+
+# Test ExpressionFunction
+expr = ExpressionFunction('x**2 + 1', [0, 1, 2])
+assert abs(expr._evaluate(3) - 10) < 1e-10
+
+# Test PolynomialCoefficients
+poly = PolynomialCoefficients([1, 2, 3], [0, 1, 2])  # 3x²+2x+1
+assert poly._evaluate(2) == 17
+
+print('All tests passed!')
+"
+```
+
+## Version History
+
+- **1.0.0** — Initial release with 40+ function classes
+- **1.1.0** — Added `PolynomialCoefficients` and `ExpressionFunction` classes; enhanced special functions coverage
+
+## Roadmap
+
+- Parametric and polar plotting support
+- 3D surface plotting (`plot_surface`)
+- Animation support for time-varying functions
+- LaTeX formula rendering in labels
+- Export to SVG/PDF formats
+- Interactive widgets (ipywidgets integration)
+- Type hints and full mypy compatibility
+- Comprehensive test suite with pytest
+
+## License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
+
+## Author
+
+**Marc Pérez** — [GitHub](https://github.com/marc1fino)
+
+---
+
+*Mathematical function plotting for education, research, and engineering.*