# NeuroFlow

**Repository Path**: javpower/neuroflow

## Basic Information

- **Project Name**: NeuroFlow
- **Description**: NeuroFlow深度学习框架
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NeuroFlow

一个为Java设计的综合性深度学习框架，提供自动微分、神经网络层、优化器和强化学习算法。

## 概述

NeuroFlow是一个纯Java深度学习框架，旨在具备教育性、可扩展性和高性能。它通过计算图支持自动微分、各种神经网络架构和常见的优化算法。

## 特性

### 核心特性
- **N维数组 (NDArray)**：支持CPU/GPU的多维张量运算
- **自动微分**：基于计算图的梯度计算
- **神经网络层**：全连接层、卷积层、池化层、Dropout、批量归一化、激活函数
- **优化算法**：SGD、Adam等优化器
- **损失函数**：交叉熵、MSE等常见损失函数
- **训练工具**：模型训练、验证和历史记录追踪

### 强化学习
- **多臂老虎机**：ε-贪婪和UCB算法
- **策略梯度**：REINFORCE算法
- **深度Q学习**：DQN实现

### 设备支持
- **CPU**：原生CPU计算
- **GPU**：通过JCuda支持CUDA（可选）

## 安装

### 前置要求
- Java 8 或更高版本
- Maven 3.6 或更高版本

### 从源码构建

```bash
git clone https://github.com/javpower/neuroflow.git
cd neuroflow
mvn clean install
```

### Maven依赖

```xml
<dependency>
    <groupId>io.github.javpower</groupId>
    <artifactId>neuroflow</artifactId>
    <version>1.0.0</version>
</dependency>
```

## 快速开始

### 基础神经网络示例

```java
import com.neuroflow.core.*;
import com.neuroflow.nn.*;
import com.neuroflow.ml.*;

// 创建训练数据
NDArray X = new NDArray(new double[][]{
    {0.0, 0.0},
    {0.0, 1.0},
    {1.0, 0.0},
    {1.0, 1.0}
});

NDArray y = new NDArray(new double[][]{
    {0.0},
    {1.0},
    {1.0},
    {0.0}
});

// 创建简单的神经网络
Model model = new Model("xor_network");
model.add(new Linear(2, 4, "hidden"));
model.add(new ReLULayer("relu"));
model.add(new Linear(4, 1, "output"));
model.add(new SigmoidLayer("sigmoid"));

// 初始化并训练
model.getNetwork().initialize();
SGD optimizer = new SGD(0.1);
MSELoss lossFunction = new MSELoss();

// 训练循环
for (int epoch = 0; epoch < 1000; epoch++) {
    NDArray output = model.forward(X);
    NDArray loss = lossFunction.forward(output, y);

    // 反向传播和权重更新
    loss.backward();
    optimizer.step(model.getParameters(), model.getGradients());
    model.zeroGrad();

    if (epoch % 100 == 0) {
        System.out.printf("Epoch %d, Loss: %.4f%n", epoch, loss.sum());
    }
}
```

### 卷积神经网络示例

```java
// 创建用于图像分类的CNN
Model cnn = new Model("cnn_model");

// 卷积层
cnn.add(new Conv2d(3, 32, 3, 1, 1, "conv1"));
cnn.add(new ReLULayer("relu1"));
cnn.add(new MaxPool2d(2, 2, 0, "pool1"));

cnn.add(new Conv2d(32, 64, 3, 1, 1, "conv2"));
cnn.add(new ReLULayer("relu2"));
cnn.add(new MaxPool2d(2, 2, 0, "pool2"));

// 全连接层
cnn.add(new Linear(64 * 8 * 8, 128, "fc1"));
cnn.add(new ReLULayer("fc1_relu"));
cnn.add(new Dropout(0.5, "dropout"));
cnn.add(new Linear(128, 10, "output"));

// 初始化网络
cnn.getNetwork().initialize();

// 打印模型摘要
cnn.summary();
```

### 强化学习示例

```java
// 使用ε-贪婪策略的多臂老虎机
int numArms = 10;
EpsilonGreedyAgent agent = new EpsilonGreedyAgent(numArms, 0.1, "bandit_agent");

// 模拟老虎机环境
MultiArmedBandit bandit = new MultiArmedBandit(numArms);

for (int episode = 0; episode < 1000; episode++) {
    int action = agent.selectAction();
    double reward = bandit.pullArm(action);
    agent.update(action, reward);

    if (episode % 100 == 0) {
        System.out.printf("回合 %d, 总奖励: %.2f%n",
                         episode, agent.getTotalReward());
    }
}
```

## 架构

### 核心组件

#### NDArray
用于多维数组运算的基础数据结构：
```java
// 创建数组
NDArray a = NDArrayFactory.zeros(new int[]{3, 4}, Device.CPU, DType.FLOAT64);
NDArray b = NDArrayFactory.randn(new int[]{3, 4}, Device.CPU, DType.FLOAT64);

// 运算
NDArray c = a.add(b);
NDArray d = a.matmul(b.transpose());

// 降维操作
double sum = c.sum();
double mean = c.mean();
```

#### 神经网络层
所有层都继承基础的`Layer`类：
```java
public class CustomLayer extends Layer {
    public CustomLayer(String name) {
        super(name);
    }

    @Override
    public NDArray forward(NDArray input) {
        // 自定义前向传播逻辑
        return processedInput;
    }

    @Override
    public int getParameterCount() {
        // 返回参数数量
        return 0;
    }

    @Override
    public void initialize() {
        // 初始化参数
    }
}
```

#### 自动微分
变量维护用于梯度计算的计算图：
```java
Variable x = new Variable(inputData, true, "x");
Variable y = new Variable(targetData, true, "y");

Variable z = x.add(y).multiply(new Variable(2.0));

z.backward(); // 自动计算梯度
NDArray gradX = x.getGrad();
NDArray gradY = y.getGrad();
```

## API参考

### 核心类

#### NDArrayFactory
创建NDArray的工厂方法：
- `zeros(shape, device, dtype)` - 填充零的数组
- `ones(shape, device, dtype)` - 填充一的数组
- `rand(shape, device, dtype)` - 均匀随机值
- `randn(shape, device, dtype)` - 正态随机值
- `xavier(shape, device, dtype)` - Xavier初始化
- `he(shape, device, dtype)` - He初始化

#### 神经网络层

**全连接层**
```java
Linear layer = new Linear(inputSize, outputSize, useBias, name);
```

**卷积层**
```java
Conv2d conv = new Conv2d(inChannels, outChannels, kernelSize, stride, padding, useBias, name);
```

**激活层**
```java
ReLULayer relu = new ReLULayer(name);
SigmoidLayer sigmoid = new SigmoidLayer(name);
```

**池化层**
```java
MaxPool2d pool = new MaxPool2d(kernelSize, stride, padding, name);
```

**Dropout层**
```java
Dropout dropout = new Dropout(dropoutRate, name);
```

**批量归一化**
```java
BatchNorm batchNorm = new BatchNorm(numFeatures, epsilon, momentum, name);
```

#### 优化器

**SGD**
```java
SGD optimizer = new SGD(learningRate);
optimizer.step(parameters, gradients);
```

**Adam**
```java
Adam optimizer = new Adam(learningRate, beta1, beta2, epsilon);
optimizer.step(parameters, gradients);
```

#### 损失函数

**均方误差**
```java
MSELoss loss = new MSELoss();
NDArray lossValue = loss.forward(predictions, targets);
```

**交叉熵**
```java
CrossEntropyLoss loss = new CrossEntropyLoss();
NDArray lossValue = loss.forward(logits, targets);
```

## 示例

`examples/`目录包含各种示例：

- **MNIST分类**：使用CNN进行手写数字识别
- **XOR问题**：解决XOR问题的简单神经网络
- **强化学习**：各种RL算法实现
- **自编码器**：降维和特征学习

## 测试

运行测试套件：
```bash
mvn test
```

运行特定测试类：
```bash
mvn test -Dtest=NDArrayTest
mvn test -Dtest=NeuralNetworkTest
```

## 性能考虑

- 根据精度要求使用适当的数据类型（FLOAT32 vs FLOAT64）
- 对于大规模计算考虑GPU加速
- 尽可能批处理操作以获得更好的缓存利用率
- 使用适当的初始化方法以获得更好的收敛性

## 贡献

我们欢迎贡献！请查看我们的[贡献指南](CONTRIBUTING.md)了解详情。

### 开发环境设置

1. Fork仓库
2. 创建功能分支：`git checkout -b feature-name`
3. 进行更改并添加测试
4. 运行测试：`mvn test`
5. 提交拉取请求

### 代码风格

- 遵循Java编码约定
- 使用有意义的变量和方法名
- 为公共API添加Javadoc注释
- 保持方法专注和简洁

## 许可证

本项目采用MIT许可证 - 详情请参阅[LICENSE](LICENSE)文件。

## 致谢

- 灵感来源于流行的深度学习框架如PyTorch和TensorFlow
- 使用标准Java库构建以获得最大兼容性
- 特别感谢开源社区提供的宝贵反馈和贡献

## 引用

如果您在研究中使用NeuroFlow，请引用：

```bibtex
@software{neuroflow,
  title={NeuroFlow: A Deep Learning Framework for Java},
  author={Your Name},
  year={2024},
  url={https://github.com/your-username/neuroflow}
}
```

## 路线图

- [ ] GPU加速改进
- [ ] 更多神经网络架构（RNN、LSTM、Transformer）
- [ ] 高级优化算法
- [ ] 分布式训练支持
- [ ] 模型序列化和加载
- [ ] 可视化工具
- [ ] 与流行Java ML库的集成

---

## 中文使用指南

### 常见问题解答

**Q: NeuroFlow支持哪些Java版本？**
A: NeuroFlow支持Java 8及以上版本。

**Q: 如何在GPU上运行计算？**
A: 确保安装了NVIDIA显卡和CUDA驱动，然后使用Device.GPU创建NDArray：
```java
NDArray gpuArray = NDArrayFactory.randn(shape, Device.GPU, DType.FLOAT64);
```

**Q: 如何创建自定义的神经网络层？**
A: 继承Layer类并实现必要的方法：
```java
public class MyLayer extends Layer {
    public MyLayer(String name) {
        super(name);
    }

    @Override
    public NDArray forward(NDArray input) {
        // 实现前向传播
        return result;
    }

    @Override
    public int getParameterCount() {
        // 返回参数数量
        return 0;
    }

    @Override
    public void initialize() {
        // 初始化参数
    }
}
```

**Q: 如何保存和加载模型？**
A: 目前NeuroFlow提供基本的序列化支持，您可以将模型参数保存到文件：
```java
// 保存模型
NDArray[] parameters = model.getParameters();
// 实现保存逻辑...

// 加载模型
// 实现加载逻辑...
model.getNetwork().setParameters(loadedParameters);
```

**Q: 如何调试训练过程？**
A: 使用TrainingHistory类来跟踪训练进度：
```java
TrainingHistory history = new TrainingHistory();
// 每个epoch后记录
history.addEpoch(trainLoss, valLoss);
// 打印摘要
history.printSummary();
```

**Q: NeuroFlow与其他深度学习框架相比如何？**
A: NeuroFlow专注于为Java生态系统提供纯Java的深度学习解决方案，具有以下优势：
- 完全用Java编写，无本地依赖
- 适合Java开发和部署环境
- 良好的教育价值和学习曲线
- 轻量级且易于扩展

### 教程资源

1. **新手入门**：从简单的线性回归开始
2. **神经网络基础**：理解反向传播和梯度下降
3. **卷积神经网络**：图像处理入门
4. **强化学习**：智能体训练基础
5. **高级技巧**：模型优化和部署