کتابخانهای جامع و ماژولار برای ابزارهای ریاضی، آماری، ماتریسی، رگرسیون خطی و رسم نمودار در پایتون.
مجموعهای از پرکاربردترین عملیات ریاضی در قالب کلاسها و توابعی ساده و خوانا — بدون نیاز به نوشتن کدهای تکراری.
MathTool یک کتابخانهی جامع و ماژولار است که مجموعهای از پرکاربردترین عملیات ریاضی را در قالب کلاسها و توابعی ساده و خوانا در اختیار شما قرار میدهد. این ابزار با تکیه بر NumPy برای محاسبات برداری، SymPy برای محاسبات نمادین، Pandas برای مدیریت داده و Matplotlib برای رسم نمودار، به شما امکان میدهد بدون نوشتن کدهای تکراری، به سرعت به نتایج دقیق برسید.
مناسب برای محاسبات آماری و ریاضی در حوزههای دانشگاهی و پژوهشی.
برای محاسبه سریع معیارهای خطا (MSE، RMSE) و ارزیابی مدل رگرسیون.
برای محاسبات توصیفی، نرمالسازی دادهها و رسم نمودارهای مقایسهای.
برای نمونهسازی سریع الگوریتمها و آزمون ایدههای ریاضی.
هر آنچه برای محاسبات روزمره ریاضی نیاز دارید، در یک کتابخانه سبک.
پذیرش هر ساختار تو در تو (لیست، تاپل، جنریتور، آرایه NumPy، Series پانداس) و تبدیل خودکار به آرایه یکبعدی.
محاسبه مشتق معمولی و جزئی چندمتغیره با استفاده از SymPy.
پشتیبانی از بازه، لیست، ترکیب دو لیست، دو تابع و عملگر دلخواه (+، −، ×، ÷، **، %).
میانگین، واریانس، انحراف معیار، نرمالسازی Z-Score و بازه چبیشف.
شناسایی خودکار ماتریسهای همانی، قطری، اسکالر، مربعی، سطری، ستونی و تهی.
محاسبه MSE و RMSE با اعتبارسنجی ابعاد و مدیریت ورودیهای ناهمخوان.
ساخت مدل روی دیتافریم، پیشبینی و محاسبه خطای مدل با فرمول بسته.
ساخت دیتاست نمونه و خواندن/ساخت خودکار فایلهای CSV.
نمودار خطی، پراکندگی و مقایسه دو تابع با برچسبگذاری خودکار.
پوشش تست واحد با unittest برای تمامی کلاسها و توابع.
پیشنیاز: پایتون نسخه ۳.۸ یا بالاتر
<> Code
→
۲. Download ZIP
→
۳. استخراج فایل
بدون نیاز به Git. با کلیک روی دکمهی زیر، فایل ZIP پروژه مستقیماً دانلود میشود.
دانلود ZIP مستقیماگر Git دارید، مخزن را کلون کنید:
git clone https://github.com/kiarashsardari/Math-Tool.git cd Math-Tool
این کتابخانه به چهار پکیج نیاز دارد که در فایل requirements.txt تعریف شدهاند:
numpy>=1.20 pandas>=1.3 matplotlib>=3.4 sympy>=1.8
برای نصب تمام پیشنیازها، در ریشه پروژه اجرا کنید:
pip install -r requirements.txt
سپس فایل math_tool.py را در کنار پروژه خود قرار دهید یا در مسیر PYTHONPATH کپی کنید. نیازی به نصب پکیج جداگانهای نیست.
pip را بهروزرسانی کنید:
python -m pip install --upgrade pip
اگر فقط به یکی از فایلها نیاز دارید، مستقیم دانلود کنید:
یک نمونه کامل از کاربرد کلاسها و توابع کتابخانه.
import numpy as np
import pandas as pd
import sympy as sp
from math_tool import (
Settings, Stats, Matrix, Metrics,
LinearRegression, DataHandler, Plots,
derivative, sigma,
)
# ۱. تختسازی ورودی
data = [1, 2, [3, (4, 5)], np.array([[6, 7], [8, 9]])]
flat = Settings(data).x
print(flat) # [1 2 3 4 5 6 7 8 9]
# ۲. مشتق نمادین
x = sp.Symbol('x')
f = 2 * x**3 + 3 * x - 6
print(derivative(f, x)) # 6*x**2 + 3
# ۳. سیگمای بازهای
total = sigma(0, 10, lambda i: 2 * i)
print(total) # 110
# ۴. محاسبات آماری
s = Stats([1, 2, 3, 4, 5])
print(s.loc()) # 3.0
print(s.variance()) # 2.0
print(s.scale()) # 1.4142...
print(s.norm()) # [-1.414 -0.707 0. 0.707 1.414]
print(s.chebyshev(2)) # (-1.414, 7.414)
# ۵. تشخیص نوع ماتریس
print(Matrix([[1, 0], [0, 1]]).detect_matrix()) # ('identity', (2, 2))
# ۶. معیار خطا
print(Metrics.mse([3, -0.5, 2, 7], [2.5, 0.0, 2, 8])) # 0.375
# ۷. رگرسیون خطی
df = pd.DataFrame({'x': [1, 2, 3, 4, 5], 'y': [7, 4, 1, -2, -5]})
model = LinearRegression(df, 'x', 'y')
print(model.t0, model.t1) # 10.0 -3.0
print(model.predict(10)) # -20.0
# ۸. مدیریت داده
df_sample = DataHandler.make_sample_dataset(50)
# ۹. رسم نمودار
Plots.show_plot([1, 2, 3, 4], [1, 4, 9, 16])
مرجع کامل کلاسها و توابع موجود در math_tool.py بههمراه پارامترها و مثال.
Settings(x)سازنده کلاس؛ ورودی را به آرایه NumPy یکبعدی تخت تبدیل میکند. دیکشنری و مجموعه پذیرفته نمیشوند.
| پارامتر | نوع | توضیح |
|---|---|---|
x | any | هر داده قابل تختسازی (بهجز dict و set) |
ویژگی عمومی: .x — آرایه NumPy یکبعدی.
خطاها: ValueError برای dict یا set.
>>> Settings([1, 2, [3, (4, 5)], np.array([[6, 7]])]).x array([1, 2, 3, 4, 5, 6, 7], dtype=object)
is_empty()بررسی میکند آیا ورودی خالی است (آرایه خالی یا همه اعضا None).
بازگشتی: bool — True اگر خالی باشد.
>>> Settings([None]).is_empty() True >>> Settings([None, 1]).is_empty() False
flat_and_array()تختسازی کامل و بازگرداندن آرایه NumPy یکبعدی.
بازگشتی: numpy.ndarray — آرایهای یکبعدی از عناصر.
>>> Settings([[1, 2], [3, 4]]).flat_and_array() array([1, 2, 3, 4], dtype=object)
is_iter(x) [static]بررسی iterable بودن، با استثنای str، dict و set.
بازگشتی: bool
>>> Settings.is_iter([1, 2])
True
>>> Settings.is_iter(12)
False
>>> Settings.is_iter("hello")
False
derivative(f, *symbols)مشتق معمولی یا مشتق جزئی چندمتغیره با استفاده از SymPy. رشته بهطور خودکار به Symbol تبدیل میشود.
| پارامتر | نوع | توضیح |
|---|---|---|
f | SymPy expression | عبارت نمادین برای مشتقگیری |
*symbols | Symbol | str | یک یا چند نماد |
بازگشتی: یک عبارت تکی اگر یک نماد بدهید، یا لیستی از مشتقها.
>>> import sympy as sp
>>> x = sp.Symbol('x')
>>> derivative(2*x**3 + 3*x - 6, x)
6*x**2 + 3
>>> a, b = sp.symbols('a b')
>>> derivative(2*a**3 + 3*b**2, a, b)
[6*a**2, 6*b]
sigma(i=None, n=None, f=identity, g=identity, operator=None)سیگمای جامع با پشتیبانی از بازه، لیست، دو لیست، دو تابع و عملگر دلخواه.
| پارامتر | نوع | توضیح |
|---|---|---|
i | int | iterable | None | کران پایین یا لیست اول |
n | int | iterable | None | کران بالا یا لیست دوم |
f | callable | تابع اول (پیشفرض: همانی) |
g | callable | تابع دوم (اختیاری، برای حالت دو تابع) |
operator | str | عملگر: +، -، *، /، **، % |
حالت ۱ — بازه با یک تابع:
>>> sigma(0, 10, lambda i: 2*i) 110
حالت ۲ — لیست با یک تابع:
>>> sigma([1, 2, 3, 4], f=lambda x: 2*x) 20
حالت ۳ — دو لیست با عملگر و یک تابع:
>>> i, n = [1, 2, 3, 4, 5], [6, 7, 8, 9, 10] >>> sigma(i, n, f=lambda x: 2*x, operator='-') -50
حالت ۴ — دو لیست با دو تابع و عملگر:
>>> sigma( ... [1, 2, 3, 4, 5], ... [6, 7, 8, 9, 10], ... f=lambda x: 2*x, ... g=lambda x: x - 1, ... operator='-', ... ) -5
bool بهعنوان عدد صحیح پذیرفته نمیشود تا از سوءاستفاده جلوگیری شود.
Stats(nums)سازنده کلاس؛ ورودی را تخت کرده و به اعداد تبدیل میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
nums | array-like | مجموعه اعداد ورودی |
خطاها: ValueError برای ورودی خالی، TypeError برای مقادیر غیرعددی.
loc()میانگین حسابی (Mean) عناصر را محاسبه میکند.
بازگشتی: float — میانگین.
>>> Stats([1, 2, 3, 4, 5]).loc() 3.0
variance()واریانس جامعه (تقسیم بر n) را محاسبه میکند.
بازگشتی: float — واریانس.
n)، نه نمونه (تقسیم بر n-1).
>>> Stats([1, 2, 3, 4, 5]).variance() 2.0
scale()انحراف معیار (Standard Deviation) بهعنوان جذر واریانس.
بازگشتی: float
>>> Stats([2, 4, 4, 4, 5, 5, 7, 9]).scale() 2.0
norm()نرمالسازی Z-Score؛ هر مقدار به (x − μ) / σ تبدیل میشود.
بازگشتی: numpy.ndarray
>>> Stats([1, 2, 3, 4, 5]).norm() array([-1.41421356, -0.70710678, 0. , 0.70710678, 1.41421356])
chebyshev(k)بازه چبیشف را بهصورت [μ − kσ, μ + kσ] محاسبه میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
k | int | float | ضریب بازه (باید بزرگتر از صفر باشد) |
بازگشتی: tuple[float, float] — کران پایین و بالا.
خطاها: ValueError اگر k ≤ 0.
>>> Stats([1, 2, 3, 4, 5]).chebyshev(2) (-1.4142135623730951, 7.414213562373095)
Matrix(M)سازنده کلاس؛ ماتریس ورودی را به آرایه NumPy تبدیل میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
M | array-like | ماتریس یا آرایه ورودی |
ویژگی عمومی: .M — آرایه NumPy ماتریس.
detect_matrix()نوع ماتریس را بههمراه ابعاد آن تشخیص میدهد.
بازگشتی: tuple[str | None, tuple] — (نوع، shape)
| نوع | توضیح |
|---|---|
'null' | تمام درایهها صفر |
'rectangular' | ماتریس مستطیلی عمومی |
'square' | ماتریس مربعی غیرقطری |
'diagonal' | قطری با درایههای قطری ناهمگون |
'scalar' | قطری با درایههای قطری مساوی |
'identity' | قطری با درایههای قطری برابر ۱ |
'column' | ماتریس ستونی (n×1) |
'row' | ماتریس سطری (1×n) |
خطاها: ValueError اگر آرایه بیش از دو بعد داشته باشد.
>>> Matrix([[1, 0, 0], [0, 2, 0], [0, 0, 3]]).detect_matrix()
('diagonal', (3, 3))
>>> Matrix([[1, 0], [0, 1]]).detect_matrix()
('identity', (2, 2))
>>> Matrix([[0, 0], [0, 0]]).detect_matrix()
('null', (2, 2))
matrix_equal(B)بررسی میکند آیا دو ماتریس از نظر شکل و محتوا کاملاً یکسان هستند.
| پارامتر | نوع | توضیح |
|---|---|---|
B | array-like | ماتریس دوم برای مقایسه |
بازگشتی: bool
>>> Matrix([[1, 2], [3, 4]]).matrix_equal([[1, 2], [3, 4]]) True >>> Matrix([[1, 2]]).matrix_equal([[1, 2], [3, 4]]) False
mse(y_true, y_pred) [static]میانگین مربع خطا (Mean Squared Error) را محاسبه میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
y_true | array-like | مقادیر واقعی |
y_pred | array-like | مقادیر پیشبینیشده |
بازگشتی: float | None — مقدار MSE، یا None اگر ابعاد ناهمخوان یا آرایه خالی باشند.
>>> Metrics.mse([3, -0.5, 2, 7], [2.5, 0.0, 2, 8]) 0.375
rmse(mse_value) [static]جذر میانگین مربع خطا (Root Mean Squared Error) را از مقدار MSE محاسبه میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
mse_value | float | None | مقدار MSE که قبلاً محاسبه شده |
بازگشتی: float | None
>>> Metrics.rmse(0.375) 0.6123724356957945
show_plot(x, y) [static]نمودار خطی ساده از دادههای x و y رسم میکند.
>>> Plots.show_plot([1, 2, 3, 4], [1, 4, 9, 16]) True
show_scatter(x, y) [static]نمودار پراکندگی (Scatter) ساده رسم میکند.
>>> Plots.show_scatter([1, 2, 3], [4, 5, 6]) True
comparison_plot(f_true, f_pred) [static]نمودار مقایسهای دو تابع را در بازه x ∈ [1, 10] با ۱۰۰ نقطه رسم میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
f_true | callable | تابع مرجع (برچسب truth) |
f_pred | callable | تابع پیشبینی (برچسب guess) |
بازگشتی: bool — پس از نمایش نمودار.
>>> Plots.comparison_plot( ... f_true=lambda x: 2*x, ... f_pred=lambda x: 3*x + 3, ... ) True
LinearRegression(df, x_name, y_name)سازنده کلاس؛ مدل رگرسیون خطی ساده با فرمول بسته را روی ستونهای دیتافریم میسازد.
| پارامتر | نوع | توضیح |
|---|---|---|
df | pandas.DataFrame | دیتافریم ورودی |
x_name | str | نام ستون مستقل |
y_name | str | نام ستون وابسته |
ویژگیهای عمومی: t0 و t1 — ضرایب مدل.
>>> df = pd.DataFrame({'x': [1, 2, 3, 4, 5], 'y': [7, 4, 1, -2, -5]})
>>> model = LinearRegression(df, 'x', 'y')
>>> model.t0, model.t1
(10.0, -3.0)
coefficients()ضرایب مدل را (دوباره) محاسبه میکند و خود شیء را برمیگرداند.
بازگشتی: LinearRegression — خود شیء (برای زنجیرهسازی).
predict(x)پیشبینی مقدار y برای ورودی x با استفاده از مدل آموزشدیده.
| پارامتر | نوع | توضیح |
|---|---|---|
x | array-like | scalar | مقدار(های) مستقل |
بازگشتی: ndarray | float
>>> model.predict(10) -20.0
model_mse(x, y_true)خطای MSE مدل را روی دادههای ورودی محاسبه میکند.
بازگشتی: float | None
>>> model.model_mse([1, 2, 3, 4, 5], [7, 4, 1, -2, -5]) 0.0
make_sample_dataset(n, seed=313) [static]دیتاست نمونه از سن و قد با نویز مصنوعی میسازد و در فایل sample_dataset.csv ذخیره میکند.
| پارامتر | نوع | توضیح |
|---|---|---|
n | int | تعداد رکوردها |
seed | int | بذر تصادفی (پیشفرض ۳۱۳) |
بازگشتی: pandas.DataFrame
>>> df = DataHandler.make_sample_dataset(100) >>> df.head()
read_or_make_csv(address, make_dataset_function, *args) [static]اگر فایل CSV موجود باشد میخواند، در غیر این صورت با تابع دادهشده آن را میسازد.
| پارامتر | نوع | توضیح |
|---|---|---|
address | str | مسیر فایل CSV |
make_dataset_function | callable | تابع سازنده دیتاست |
*args | any | آرگومانهای ارسالی به تابع سازنده |
بازگشتی: pandas.DataFrame
>>> df = DataHandler.read_or_make_csv( ... "data.csv", ... DataHandler.make_sample_dataset, ... 100, ... )
چند سناریوی واقعی برای استفاده از MathTool.
ترکیب توابع آمار توصیفی، بازه چبیشف و نرمالسازی برای تحلیل نمرات.
from math_tool import Stats
scores = [78, 85, 90, 92, 88, 75, 95, 82, 79, 91]
s = Stats(scores)
mean = s.loc()
var = s.variance()
std = s.scale()
interval = s.chebyshev(2)
normalized = s.norm()
print(f"میانگین: {mean:.2f}")
print(f"انحراف معیار: {std:.2f}")
print(f"بازه چبیشف (k=2): [{interval[0]:.2f}, {interval[1]:.2f}]")
print(f"دادههای نرمالشده: {normalized.round(2)}")
محاسبه MSE و RMSE برای سنجش دقت پیشبینی مدل.
from math_tool import Metrics
y_true = [2.5, 3.1, 4.8, 5.2, 6.0]
y_pred = [2.4, 3.3, 4.5, 5.5, 5.9]
mse_val = Metrics.mse(y_true, y_pred)
rmse_val = Metrics.rmse(mse_val)
print(f"MSE = {mse_val:.4f}")
print(f"RMSE = {rmse_val:.4f}")
محاسبه مشتق نمادین با SymPy و رسم مقایسه با تابع اصلی.
import sympy as sp
from math_tool import derivative, Plots
x = sp.Symbol('x')
f = x**3 - 3*x**2 + 2*x + 1
# مشتق نسبت به x
print(derivative(f, x)) # 3*x**2 - 6*x + 2
# رسم مقایسه با تابع اصلی
Plots.comparison_plot(
f_true=sp.lambdify(x, f, 'numpy'),
f_pred=lambda t: t**3 - 3*t**2 + 2*t + 1.5,
)
شناسایی خودکار انواع ماتریس با استفاده از detect_matrix.
from math_tool import Matrix
matrices = {
"همانی": [[1, 0, 0], [0, 1, 0], [0, 0, 1]],
"اسکالر": [[5, 0, 0], [0, 5, 0], [0, 0, 5]],
"قطری": [[1, 0, 0], [0, 2, 0], [0, 0, 3]],
"پوچ": [[0, 0], [0, 0]],
"ستونی": [[1], [2], [3]],
"سطری": [[1, 2, 3]],
"مستطیلی": [[1, 2, 3], [4, 5, 6]],
}
for name, M in matrices.items():
typ, shape = Matrix(M).detect_matrix()
print(f"{name:12s} → {typ:12s} {shape}")
همانی → identity (3, 3) اسکالر → scalar (3, 3) قطری → diagonal (3, 3) پوچ → null (2, 2) ستونی → column (3, 1) سطری → row (1, 3) مستطیلی → rectangular (2, 3)
ساخت دیتاست نمونه، آموزش مدل رگرسیون و پیشبینی.
from math_tool import DataHandler, LinearRegression, Plots
# ۱. ساخت یا خواندن دیتاست
df = DataHandler.read_or_make_csv(
"sample_dataset.csv",
DataHandler.make_sample_dataset,
100,
)
# ۲. آموزش مدل
model = LinearRegression(df, "age", "height")
print(f"θ₀ = {model.t0:.3f}")
print(f"θ₁ = {model.t1:.3f}")
# ۳. پیشبینی برای سن ۳۰
print(model.predict(30))
# ۴. محاسبه خطای مدل
print(model.model_mse(df["age"], df["height"]))
# ۵. نمایش نمودار مقایسه
Plots.comparison_plot(
f_true=lambda a: df["height"].mean(),
f_pred=model.predict,
)
کتابخانه دارای مجموعه تست واحد با unittest است.
python -m unittest test_math_tool.py -v
Math-Tool/ ├── math_tool.py # هسته کتابخانه ├── test_math_tool.py # مجموعه تستهای واحد ├── requirements.txt # وابستگیهای پروژه └── README.md # مستندات پروژه
math_tool.pymath_tool.py
│
├── Settings (class)
│ ├── is_empty()
│ ├── flat_and_array()
│ └── is_iter(x) [static]
│
├── derivative(f, *symbols) [function]
├── sigma(...) [function]
│
├── Stats (class)
│ ├── loc()
│ ├── variance()
│ ├── scale()
│ ├── norm()
│ └── chebyshev(k)
│
├── Plots (class)
│ ├── comparison_plot(f_true, f_pred) [static]
│ ├── show_plot(x, y) [static]
│ └── show_scatter(x, y) [static]
│
├── Matrix (class)
│ ├── detect_matrix()
│ └── matrix_equal(B)
│
├── Metrics (class)
│ ├── mse(y_true, y_pred) [static]
│ └── rmse(mse_value) [static]
│
├── LinearRegression (class)
│ ├── coefficients()
│ ├── predict(x)
│ └── model_mse(x, y_true)
│
└── DataHandler (class)
├── make_sample_dataset(n, seed=313) [static]
└── read_or_make_csv(address, make_fn, *args) [static]
requirements.txtnumpy>=1.20 pandas>=1.3 matplotlib>=3.4 sympy>=1.8