pylib-matlab 1.0.0
全面兼容MATLAB的Python数学建模库
License: MIT
Requires Python: >=3.8
Keywords: matlab, mathematics, numerical-computation, data-visualization, machine-learning, signal-processing, image-processing, control-systems

# pylib - 全面兼容MATLAB的Python数学建模库

## 1. 项目概述

pylib是一个功能全面的Python数学建模库，充分利用Python生态系统的优势。该库集成了核心数学计算、数据处理、可视化和建模算法，为科学计算、工程设计和数据分析提供了一站式解决方案。

### 1.1 主要特点

- **MATLAB兼容**：函数命名和用法与MATLAB高度一致，便于MATLAB用户快速迁移
- **全面的功能覆盖**：从基础数学到高级建模，涵盖科学计算的各个领域
- **模块化设计**：清晰的模块结构，便于学习和使用
- **高性能**：基于NumPy、SciPy等高性能库实现
- **易于扩展**：开放的架构设计，支持用户自定义功能
- **完整的文档**：详细的API参考和丰富的示例代码

### 1.2 适用场景

- 科学计算与数值分析
- 工程设计与仿真
- 数据分析与可视化
- 机器学习与深度学习
- 信号处理与图像处理
- 控制系统设计
- 优化问题求解

## 2. 目录结构

```
pylib/
├── __init__.py          # 库初始化文件
├── core/                # 核心数学计算模块
│   ├── __init__.py
│   ├── math.py          # 基础数学函数
│   ├── linalg.py        # 线性代数
│   ├── calculus.py      # 微积分
│   ├── equations.py     # 方程求解
│   ├── optimization.py  # 优化算法
│   └── statistics.py    # 统计分析
├── data/                # 数据处理模块
│   ├── __init__.py
│   ├── io.py            # 数据输入输出
│   ├── cleaning.py      # 数据清洗
│   ├── transformation.py # 数据变换
│   └── preprocessing.py # 数据预处理
├── visualization/       # 可视化模块
│   ├── __init__.py
│   ├── plots/           # 基本图表
│   ├── charts/          # 高级图表
│   ├── three_d/         # 3D图表
│   └── advanced/        # 高级可视化
└── modeling/            # 建模算法与工具
    ├── __init__.py
    ├── ml.py            # 机器学习
    ├── dl.py            # 深度学习
    ├── signal.py        # 信号处理
    ├── image.py         # 图像处理
    ├── control.py       # 控制系统
    └── optimization.py  # 优化算法
```

## 3. 核心功能模块

### 3.1 核心数学计算

- **基础数学函数**：三角函数、指数对数、常数定义等
- **线性代数**：矩阵运算、行列式、特征值、矩阵分解等
- **微积分**：数值微分、数值积分、符号计算等
- **方程求解**：线性方程组、非线性方程、多项式求根等
- **优化算法**：无约束优化、有约束优化、线性规划等
- **统计分析**：描述统计、概率分布、假设检验等

### 3.2 数据处理

- **数据输入输出**：支持CSV、Excel、MAT、JSON等多种格式
- **数据清洗**：缺失值处理、异常值处理、重复值处理等
- **数据变换**：标准化、归一化、编码、重塑等
- **数据预处理**：数据集分割、特征选择、降维等

### 3.3 可视化

- **基本图表**：线图、散点图、柱状图、直方图等
- **高级图表**：热图、等高线图、矢量场图等
- **3D图表**：3D线图、曲面图、等高线图等
- **高级可视化功能**：子图、标题、标签、图例等

### 3.4 建模算法与工具

- **机器学习**：分类、回归、聚类、降维等
- **深度学习**：神经网络、预训练模型、优化器等
- **信号处理**：傅里叶变换、滤波、卷积、频谱分析等
- **图像处理**：图像读写、变换、增强、滤波等
- **控制系统**：传递函数、状态空间、频率响应分析等
- **优化算法**：线性规划、二次规划、全局优化等

## 4. 安装方法

### 4.1 系统要求

- Python 3.7+
- 支持的操作系统：Windows 10/11、macOS 10.15+、Linux (Ubuntu 18.04+)

### 4.2 依赖包

pylib库基于以下高性能Python库构建：

- numpy (>=1.21.0) - 数值计算基础
- scipy (>=1.7.0) - 科学计算工具
- matplotlib (>=3.4.0) - 数据可视化
- pandas (>=1.3.0) - 数据分析
- scikit-learn (>=1.0.0) - 机器学习
- pillow (>=8.0.0) - 图像处理基础
- scikit-image (>=0.18.0) - 高级图像处理

### 4.3 安装命令

#### 方式一：直接使用pip安装依赖

```bash
pip install numpy scipy matplotlib pandas scikit-learn pillow scikit-image
```

#### 方式二：使用requirements.txt安装（推荐）

首先在项目根目录创建requirements.txt文件：

```txt
numpy>=1.21.0
scipy>=1.7.0
matplotlib>=3.4.0
pandas>=1.3.0
scikit-learn>=1.0.0
pillow>=8.0.0
scikit-image>=0.18.0
```

然后执行：

```bash
pip install -r requirements.txt
```

## 5. 快速入门

### 5.1 基本用法

```python
import pylib as pl

# 1. 基础数学计算
x = pl.core.math.sin(pl.core.math.pi / 2)  # sin(π/2) = 1.0
print(f"sin(π/2) = {x}")

# 2. 矩阵运算
A = [[1, 2], [3, 4]]
B = [[5, 6], [7, 8]]
C = pl.core.linalg.matmul(A, B)  # 矩阵乘法
print(f"矩阵乘法结果：\n{C}")

# 3. 数据处理
import numpy as np
from sklearn.datasets import load_iris

iris = load_iris()
data = iris.data

# 数据标准化
normalized_data = pl.data.transformation.normalize(data)
print(f"标准化后的数据形状：{normalized_data.shape}")

# 4. 可视化
x = np.linspace(0, 2*np.pi, 100)
y = np.sin(x)

pl.visualization.plots.plot(x, y)
pl.visualization.advanced.title('正弦函数')
pl.visualization.advanced.show()
```

### 5.2 运行示例代码

项目提供了丰富的示例代码，位于 `examples/`目录下：

```bash
# 运行基础数学示例
python -m examples.basic_math

# 运行数据处理示例
python -m examples.data_processing

# 运行机器学习和建模示例
python -m examples.modeling_demo

# 运行可视化示例
python -m examples.visualization
```

## 6. 详细教程

### 6.1 核心数学计算教程

#### 6.1.1 基础数学函数

pylib的基础数学函数与MATLAB高度兼容，包括三角函数、指数对数函数、常数定义等。

```python
import pylib as pl

# 三角函数
sin_val = pl.core.math.sin(pl.core.math.pi / 6)  # sin(30°)
cos_val = pl.core.math.cos(pl.core.math.pi / 3)  # cos(60°)
tan_val = pl.core.math.tan(pl.core.math.pi / 4)  # tan(45°)

# 指数对数
exp_val = pl.core.math.exp(1)  # e^1
log_val = pl.core.math.log(10)  # 自然对数
log10_val = pl.core.math.log10(100)  # 常用对数

# 常数
pi_val = pl.core.math.pi  # π
 e_val = pl.core.math.e   # e
```

#### 6.1.2 线性代数

pylib提供了全面的线性代数功能，包括矩阵运算、行列式、特征值等。

```python
import pylib as pl
import numpy as np

# 创建矩阵
A = np.array([[1, 2], [3, 4]])
B = np.array([[5, 6], [7, 8]])

# 矩阵乘法
C = pl.core.linalg.matmul(A, B)

# 行列式
det = pl.core.linalg.det(A)

# 逆矩阵
inv_A = pl.core.linalg.inv(A)

# 特征值和特征向量
eigvals, eigvecs = pl.core.linalg.eig(A)
```

### 6.2 数据处理教程

#### 6.2.1 数据输入输出

```python
import pylib as pl
import numpy as np

# 创建示例数据
data = np.random.rand(10, 5)

# 保存为CSV文件
pl.data.io.save_csv('data.csv', data)

# 读取CSV文件
loaded_data = pl.data.io.load_csv('data.csv')

# 保存为MAT文件
pl.data.io.save_mat('data.mat', {'data': data})

# 读取MAT文件
loaded_mat = pl.data.io.load_mat('data.mat')
```

#### 6.2.2 数据清洗

```python
import pylib as pl
import numpy as np

# 创建包含缺失值的数据
data = np.array([[1, 2, np.nan], [4, np.nan, 6], [7, 8, 9]])

# 查看缺失值
missing_mask = pl.data.cleaning.isna(data)

# 填充缺失值（使用均值）
filled_data = pl.data.cleaning.fillna(data, method='mean')

# 删除包含缺失值的行
dropped_data = pl.data.cleaning.dropna(data, axis=0)
```

### 6.3 可视化教程

#### 6.3.1 基本图表

```python
import pylib as pl
import numpy as np

# 线图
x = np.linspace(0, 2*np.pi, 100)
y1 = np.sin(x)
y2 = np.cos(x)

pl.visualization.plots.plot(x, y1, label='sin(x)', color='blue')
pl.visualization.plots.plot(x, y2, label='cos(x)', color='red')
pl.visualization.advanced.legend()
pl.visualization.advanced.title('三角函数')
pl.visualization.advanced.show()

# 散点图
x = np.random.rand(100)
y = np.random.rand(100)
colors = np.random.rand(100)
sizes = 1000 * np.random.rand(100)

pl.visualization.plots.scatter(x, y, c=colors, s=sizes, alpha=0.5)
pl.visualization.advanced.title('散点图')
pl.visualization.advanced.show()

# 柱状图
categories = ['A', 'B', 'C', 'D', 'E']
values = [10, 24, 36, 42, 18]

pl.visualization.plots.bar(categories, values, color='green')
pl.visualization.advanced.title('柱状图')
pl.visualization.advanced.show()

# 直方图
data = np.random.randn(1000)

pl.visualization.plots.hist(data, bins=30, color='purple', alpha=0.7)
pl.visualization.advanced.title('直方图')
pl.visualization.advanced.show()
```

#### 6.3.2 3D图表

```python
import pylib as pl
import numpy as np

# 3D曲面图
X, Y = np.meshgrid(np.linspace(-5, 5, 100), np.linspace(-5, 5, 100))
Z = np.sin(np.sqrt(X**2 + Y**2))

pl.visualization.three_d.surf(X, Y, Z)
pl.visualization.advanced.title('3D曲面图')
pl.visualization.advanced.show()

# 3D散点图
x = np.random.randn(100)
y = np.random.randn(100)
z = np.random.randn(100)

pl.visualization.three_d.scatter3(x, y, z, color='red', marker='o')
pl.visualization.advanced.title('3D散点图')
pl.visualization.advanced.show()
```

## 7. API参考

### 7.1 核心数学计算模块 (`pylib.core`)

#### 7.1.1 基础数学函数 (`pylib.core.math`)

| 函数名       | 描述       | 示例           |
| ------------ | ---------- | -------------- |
| `sin(x)`   | 正弦函数   | `sin(pi/2)`  |
| `cos(x)`   | 余弦函数   | `cos(pi/3)`  |
| `tan(x)`   | 正切函数   | `tan(pi/4)`  |
| `asin(x)`  | 反正弦函数 | `asin(1)`    |
| `acos(x)`  | 反余弦函数 | `acos(0.5)`  |
| `atan(x)`  | 反正切函数 | `atan(1)`    |
| `exp(x)`   | 指数函数   | `exp(1)`     |
| `log(x)`   | 自然对数   | `log(e)`     |
| `log10(x)` | 常用对数   | `log10(100)` |
| `sqrt(x)`  | 平方根     | `sqrt(16)`   |
| `abs(x)`   | 绝对值     | `abs(-5)`    |
| `ceil(x)`  | 向上取整   | `ceil(3.2)`  |
| `floor(x)` | 向下取整   | `floor(3.8)` |
| `round(x)` | 四舍五入   | `round(3.5)` |

#### 7.1.2 线性代数 (`pylib.core.linalg`)

| 函数名           | 描述             | 示例             |
| ---------------- | ---------------- | ---------------- |
| `matmul(A, B)` | 矩阵乘法         | `matmul(A, B)` |
| `det(A)`       | 行列式           | `det(A)`       |
| `inv(A)`       | 矩阵求逆         | `inv(A)`       |
| `eig(A)`       | 特征值和特征向量 | `eig(A)`       |
| `svd(A)`       | 奇异值分解       | `svd(A)`       |
| `qr(A)`        | QR分解           | `qr(A)`        |
| `lu(A)`        | LU分解           | `lu(A)`        |
| `solve(A, b)`  | 线性方程组求解   | `solve(A, b)`  |
| `norm(x)`      | 向量/矩阵范数    | `norm(x)`      |

### 7.2 数据处理模块 (`pylib.data`)

#### 7.2.1 数据输入输出 (`pylib.data.io`)

| 函数名                             | 描述          | 示例                                     |
| ---------------------------------- | ------------- | ---------------------------------------- |
| `load_csv(file_path)`            | 读取CSV文件   | `load_csv('data.csv')`                 |
| `save_csv(file_path, data)`      | 保存为CSV文件 | `save_csv('data.csv', data)`           |
| `load_mat(file_path)`            | 读取MAT文件   | `load_mat('data.mat')`                 |
| `save_mat(file_path, data_dict)` | 保存为MAT文件 | `save_mat('data.mat', {'data': data})` |

#### 7.2.2 数据清洗 (`pylib.data.cleaning`)

| 函数名                                     | 描述       | 示例                                    |
| ------------------------------------------ | ---------- | --------------------------------------- |
| `isna(data)`                             | 检测缺失值 | `isna(data)`                          |
| `fillna(data, method='mean')`            | 填充缺失值 | `fillna(data, method='median')`       |
| `dropna(data, axis=0)`                   | 删除缺失值 | `dropna(data, axis=1)`                |
| `remove_outliers(data, method='zscore')` | 移除异常值 | `remove_outliers(data, method='iqr')` |

#### 7.2.3 数据变换 (`pylib.data.transformation`)

| 函数名                   | 描述         | 示例                     |
| ------------------------ | ------------ | ------------------------ |
| `normalize(data)`      | 数据归一化   | `normalize(data)`      |
| `standardize(data)`    | 数据标准化   | `standardize(data)`    |
| `one_hot_encode(data)` | 独热编码     | `one_hot_encode(data)` |
| `min_max_scale(data)`  | 最小最大缩放 | `min_max_scale(data)`  |

#### 7.2.4 数据预处理 (`pylib.data.preprocessing`)

| 函数名                                    | 描述       | 示例                                      |
| ----------------------------------------- | ---------- | ----------------------------------------- |
| `train_test_split(X, y, test_size=0.2)` | 数据集分割 | `train_test_split(X, y, test_size=0.3)` |
| `feature_selection(data, k=5)`          | 特征选择   | `feature_selection(data, k=10)`         |
| `pca(data, n_components=2)`             | 主成分分析 | `pca(data, n_components=3)`             |

### 7.3 可视化模块 (`pylib.visualization`)

#### 7.3.1 基本图表 (`pylib.visualization.plots`)

| 函数名                         | 描述   | 示例                                      |
| ------------------------------ | ------ | ----------------------------------------- |
| `plot(x, y, **kwargs)`       | 线图   | `plot(x, y, color='red', label='line')` |
| `scatter(x, y, **kwargs)`    | 散点图 | `scatter(x, y, c=colors, s=sizes)`      |
| `bar(x, height, **kwargs)`   | 柱状图 | `bar(categories, values, color='blue')` |
| `hist(x, bins=10, **kwargs)` | 直方图 | `hist(data, bins=30, alpha=0.7)`        |
| `pie(x, **kwargs)`           | 饼图   | `pie(sizes, labels=labels)`             |

#### 7.3.2 3D图表 (`pylib.visualization.three_d`)

| 函数名                          | 描述       | 示例                              |
| ------------------------------- | ---------- | --------------------------------- |
| `plot3(x, y, z, **kwargs)`    | 3D线图     | `plot3(x, y, z, color='red')`   |
| `scatter3(x, y, z, **kwargs)` | 3D散点图   | `scatter3(x, y, z, marker='o')` |
| `surf(X, Y, Z, **kwargs)`     | 3D曲面图   | `surf(X, Y, Z, cmap='viridis')` |
| `contour3(X, Y, Z, **kwargs)` | 3D等高线图 | `contour3(X, Y, Z, levels=20)`  |

#### 7.3.3 高级可视化 (`pylib.visualization.advanced`)

| 函数名                           | 描述        | 示例                      |
| -------------------------------- | ----------- | ------------------------- |
| `title(text)`                  | 设置标题    | `title('图表标题')`     |
| `xlabel(text)`                 | 设置X轴标签 | `xlabel('X轴')`         |
| `ylabel(text)`                 | 设置Y轴标签 | `ylabel('Y轴')`         |
| `zlabel(text)`                 | 设置Z轴标签 | `zlabel('Z轴')`         |
| `legend()`                     | 显示图例    | `legend()`              |
| `grid(visible=True)`           | 显示网格    | `grid(True)`            |
| `show()`                       | 显示图表    | `show()`                |
| `savefig(fname)`               | 保存图表    | `savefig('figure.png')` |
| `subplot(nrows, ncols, index)` | 创建子图    | `subplot(2, 2, 1)`      |

### 7.4 建模算法模块 (`pylib.modeling`)

#### 7.4.1 机器学习 (`pylib.modeling.ml`)

| 函数名               | 描述         | 示例                                                |
| -------------------- | ------------ | --------------------------------------------------- |
| `classification()` | 获取分类模型 | `clf = classification()['logistic_regression']()` |
| `regression()`     | 获取回归模型 | `reg = regression()['linear_regression']()`       |
| `clustering()`     | 获取聚类模型 | `clus = clustering()['kmeans']()`                 |
| `metrics()`        | 获取评估指标 | `acc = metrics()['accuracy'](y_true, y_pred)`     |

#### 7.4.2 信号处理 (`pylib.modeling.signal`)

| 函数名                          | 描述             | 示例                         |
| ------------------------------- | ---------------- | ---------------------------- |
| `fft(x)`                      | 快速傅里叶变换   | `fft(signal)`              |
| `ifft(x)`                     | 逆快速傅里叶变换 | `ifft(fft_signal)`         |
| `filter(b, a, x)`             | 数字滤波         | `filter(b, a, signal)`     |
| `convolve(a, v, mode='full')` | 卷积运算         | `convolve(signal, kernel)` |

#### 7.4.3 图像处理 (`pylib.modeling.image`)

| 函数名                  | 描述         | 示例                           |
| ----------------------- | ------------ | ------------------------------ |
| `imread(fname)`       | 读取图像     | `imread('image.jpg')`        |
| `imwrite(fname, img)` | 保存图像     | `imwrite('output.jpg', img)` |
| `resize(img, size)`   | 调整图像大小 | `resize(img, (256, 256))`    |
| `rotate(img, angle)`  | 旋转图像     | `rotate(img, 45)`            |

## 8. MATLAB 兼容性

pylib库设计为与MATLAB 2024a兼容，许多函数名称和用法与MATLAB相似，便于MATLAB用户快速迁移到Python环境。

### 8.1 函数名称对应关系

| MATLAB函数                   | pylib函数                                      | 说明             |
| ---------------------------- | ---------------------------------------------- | ---------------- |
| `sin(x)`                   | `pl.core.math.sin(x)`                        | 正弦函数         |
| `cos(x)`                   | `pl.core.math.cos(x)`                        | 余弦函数         |
| `tan(x)`                   | `pl.core.math.tan(x)`                        | 正切函数         |
| `exp(x)`                   | `pl.core.math.exp(x)`                        | 指数函数         |
| `log(x)`                   | `pl.core.math.log(x)`                        | 自然对数         |
| `sqrt(x)`                  | `pl.core.math.sqrt(x)`                       | 平方根           |
| `abs(x)`                   | `pl.core.math.abs(x)`                        | 绝对值           |
| `pi`                       | `pl.core.math.pi`                            | π常数           |
| `e`                        | `pl.core.math.e`                             | e常数            |
| `matmul(A,B)`              | `pl.core.linalg.matmul(A,B)`                 | 矩阵乘法         |
| `det(A)`                   | `pl.core.linalg.det(A)`                      | 行列式           |
| `inv(A)`                   | `pl.core.linalg.inv(A)`                      | 矩阵求逆         |
| `eig(A)`                   | `pl.core.linalg.eig(A)`                      | 特征值和特征向量 |
| `fft(x)`                   | `pl.modeling.signal.fft(x)`                  | 快速傅里叶变换   |
| `ifft(x)`                  | `pl.modeling.signal.ifft(x)`                 | 逆快速傅里叶变换 |
| `imread('file.jpg')`       | `pl.modeling.image.imread('file.jpg')`       | 读取图像         |
| `imwrite('file.jpg', img)` | `pl.modeling.image.imwrite('file.jpg', img)` | 保存图像         |
| `plot(x,y)`                | `pl.visualization.plots.plot(x,y)`           | 绘制线图         |
| `scatter(x,y)`             | `pl.visualization.plots.scatter(x,y)`        | 绘制散点图       |
| `bar(x,y)`                 | `pl.visualization.plots.bar(x,y)`            | 绘制柱状图       |
| `hist(x)`                  | `pl.visualization.plots.hist(x)`             | 绘制直方图       |
| `title('text')`            | `pl.visualization.advanced.title('text')`    | 设置标题         |
| `xlabel('text')`           | `pl.visualization.advanced.xlabel('text')`   | 设置X轴标签      |
| `ylabel('text')`           | `pl.visualization.advanced.ylabel('text')`   | 设置Y轴标签      |
| `legend()`                 | `pl.visualization.advanced.legend()`         | 显示图例         |
| `grid()`                   | `pl.visualization.advanced.grid()`           | 显示网格         |
| `show()`                   | `pl.visualization.advanced.show()`           | 显示图表         |

### 8.2 迁移指南

从MATLAB迁移到pylib的基本步骤：

1. 将MATLAB的 `sin(x)`替换为 `pl.core.math.sin(x)`
2. 将MATLAB的矩阵运算 `A*B`替换为 `pl.core.linalg.matmul(A,B)`
3. 将MATLAB的 `plot(x,y)`替换为 `pl.visualization.plots.plot(x,y)`
4. 添加 `pl.visualization.advanced.show()`来显示图表
5. 对于复杂功能，参考API文档查找对应函数

## 9. 开发说明

### 9.1 版本控制

pylib库使用语义化版本控制：

- 主版本号 (Major): 重大功能变更，不兼容的API修改
- 次版本号 (Minor): 新功能添加，向后兼容
- 修订号 (Patch): 错误修复，向后兼容

### 9.2 贡献指南

欢迎对pylib库进行贡献！贡献流程如下：

1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开Pull Request

### 9.3 代码规范

- 遵循PEP 8代码风格指南
- 使用类型注解
- 为新功能添加文档字符串
- 为新功能添加测试用例

### 9.4 测试

项目使用pytest进行测试，测试文件位于 `tests/`目录下：

```bash
# 运行所有测试
pytest

# 运行特定模块的测试
pytest tests/test_core.py -v

# 运行特定函数的测试
pytest tests/test_core.py::test_sin -v
```

## 10. 许可证

pylib库采用MIT许可证发布，详见LICENSE文件。

## 11. 联系方式

- 项目主页：[]
- 问题反馈：[]
- 开发者：[xinyuX]
- 邮箱：[]

## 12. 更新日志

### v1.0.0 ()

- 初始版本发布
- 实现核心数学计算模块
- 实现数据处理模块
- 实现可视化模块
- 实现建模算法模块
- 提供基础示例代码
- 编写完整文档

---

**pylib** - 让Python科学计算更简单、更高效！