Cranium 是一个用纯 C99 编写的、可移植的、仅包含头文件的前馈人工神经网络库。

它支持任意深度和结构的全连接网络，并且由于采用了基于矩阵的计算方式，速度应该相当快。它特别适合资源受限的机器或无法安装额外依赖的环境。

Cranium 支持 CBLAS 集成。只需取消注释 matrix.h 中的第 7 行，即可启用 BLAS 的 sgemm 函数，实现快速的矩阵乘法。

请查看详细的文档 这里，以了解各个结构和函数的信息。

---

特性

• 激活函数
  • sigmoid
  • ReLU
  • tanh
  • softmax（分类）
  • linear（回归）
• 损失函数
  • 交叉熵损失（分类）
  • 均方误差（回归）
• 优化算法
  • 批量梯度下降
  • 随机梯度下降
  • 小批量随机梯度下降
• L2 正则化
• 学习率退火
• 简单动量
• fan-in 权重初始化
• CBLAS 支持快速矩阵乘法
• 可序列化的网络

---

使用方法

由于 Cranium 是仅包含头文件的库，只需将 src 目录复制到您的项目中，并使用 #include "src/cranium.h" 即可开始使用。

它唯一的编译器依赖是 <math.h> 头文件，因此编译时需要加上 -lm 参数。

如果您使用 CBLAS，则还需要加上 -lcblas 参数，并通过 -I 指定您机器上 BLAS 实现的路径。常见的实现包括 OpenBLAS 和 ATLAS。

经过测试，Cranium 在任何级别的 gcc 优化下都能正常工作，您可以放心使用这些优化选项。

---

示例

#include "cranium.h"

/*
这个基本示例程序是一个分类问题的框架。
训练数据应以矩阵形式表示，其中每一行代表一个数据点，
    每一列代表一个特征。
训练标签也应以矩阵形式表示，第 i 行对应第 i 个训练样本，
    每一列为 1 表示属于该类，为 0 表示不属于。
每个样本只能属于一个类别。
*/

// 创建训练数据和目标值（数据收集过程未展示）
int rows, features, classes;
float** training;
float** classes;

// 创建数据集来存储数据
DataSet* trainingData = createDataSet(rows, features, training);
DataSet* trainingClasses = createDataSet(rows, classes, classes);

// 创建一个包含 2 个输入神经元、1 层隐藏层（sigmoid 激活函数，5 个神经元）和 2 个输出神经元（softmax 激活函数）的网络
srand(time(NULL));
size_t hiddenSize[] = {5};
Activation hiddenActivation[] = {sigmoid};
Network* net = createNetwork(2, 1, hiddenSize, hiddenActivation, 2, softmax);

// 使用交叉熵损失和小批量随机梯度下降训练网络
ParameterSet params;
params.network = net;
params.data = trainingData;
params.classes = trainingClasses;
params.lossFunction = CROSS_ENTROPY_LOSS;
params.batchSize = 20;
params.learningRate = .01;
params.searchTime = 5000;
params.regularizationStrength = .001;
params.momentumFactor = .9;
params.maxIters = 10000;
params.shuffle = 1;
params.verbose = 1;
optimize(params);

// 训练后测试网络的准确率
printf("准确率是 %f\n", accuracy(net, trainingData, trainingClasses));

// 获取网络在训练后的输入数据上的预测结果
forwardPass(net, trainingData);
int* predictions = predict(net);
free(predictions);

// 将网络保存到文件
saveNetwork(net, "network");

// 释放网络和数据
destroyNetwork(net);
destroyDataSet(trainingData);
destroyDataSet(trainingClasses);

// 从文件加载之前的网络
Network* previousNet = readNetwork("network");
destroyNetwork(previousNet);

---

构建与测试

要运行测试，请查看 tests 文件夹。

Makefile 中提供了运行每组单元测试或一次性运行所有测试的命令。

---

贡献

如果您想添加新功能或发现 bug，请随时提交 pull request。

请查看 issues 标签页，寻找一些可能的改进方向。

Cranium 快速上手指南

Cranium 是一个轻量级、仅包含头文件的前馈人工神经网络库，采用纯 C99 编写。它无需复杂依赖，特别适合资源受限的环境或无法安装额外依赖的场景。

环境准备

• 操作系统：支持任何兼容 C99 标准的系统（Linux, macOS, Windows 等）。
• 编译器：需要支持 C99 的编译器（如 gcc 或 clang）。
• 前置依赖：
  • 基础模式：仅需标准数学库 <math.h>。
  • 高性能模式（可选）：若需加速矩阵运算，需安装 CBLAS 实现（推荐 OpenBLAS 或 ATLAS）。
    • 国内加速建议：在 Linux 环境下，可使用系统包管理器安装 OpenBLAS（例如 Ubuntu/Debian: sudo apt-get install libopenblas-dev，CentOS: sudo yum install openblas-devel）。

安装步骤

由于 Cranium 是 header-only（仅头文件）库，无需编译安装，只需将源码复制到项目中即可。

1. 获取源码 克隆仓库或下载源码包：

   git clone https://github.com/100/Cranium.git
   

2. 集成到项目 将 Cranium/src 目录复制到你自己的项目文件夹中。

3. 启用 CBLAS 加速（可选） 如果需要更快的矩阵乘法性能，请打开 src/matrix.h 文件，取消注释第 7 行以启用 BLAS sgemm 函数。

基本使用

1. 编译命令

在你的代码中包含头文件并开始使用。

• 基础编译命令（仅需数学库）：

  gcc your_program.c -lm -o your_program
  

• 启用 CBLAS 的编译命令： 需链接 cblas 库并指定头文件路径（以 OpenBLAS 为例）：

  gcc your_program.c -lcblas -I/path/to/openblas/include -L/path/to/openblas/lib -lopenblas -lm -o your_program
  

  (注：请根据实际安装的 BLAS 库路径调整 -I 和 -L 参数)

2. 代码示例

以下是一个完整的分类任务示例，展示了如何创建数据、构建网络、训练及预测：

#include "cranium.h"
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

int main() {
    // 假设已准备好训练数据 (rows x features) 和目标标签 (rows x classes)
    // 数据格式：每行一个样本，每列一个特征
    // 标签格式：One-hot 编码，第 i 行对应第 i 个样本
    int rows = 100;
    int features = 2;
    int classes = 2;
    
    // 此处省略数据填充过程，实际使用时请分配并填充 training 和 classes 数组
    float** training = malloc(rows * sizeof(float*));
    float** classes_target = malloc(rows * sizeof(float*));
    for(int i=0; i<rows; i++) {
        training[i] = malloc(features * sizeof(float));
        classes_target[i] = malloc(classes * sizeof(float));
        // ... 填充数据 ...
    }

    // 创建数据集对象
    DataSet* trainingData = createDataSet(rows, features, training);
    DataSet* trainingClasses = createDataSet(rows, classes, classes_target);

    // 初始化随机数种子
    srand(time(NULL));

    // 创建网络结构：
    // 2 个输入神经元 -> 1 个隐藏层 (5 个神经元，sigmoid 激活) -> 2 个输出神经元 (softmax 激活)
    size_t hiddenSize[] = {5};
    Activation hiddenActivation[] = {sigmoid};
    Network* net = createNetwork(2, 1, hiddenSize, hiddenActivation, 2, softmax);

    // 配置训练参数
    ParameterSet params;
    params.network = net;
    params.data = trainingData;
    params.classes = trainingClasses;
    params.lossFunction = CROSS_ENTROPY_LOSS; // 分类任务使用交叉熵损失
    params.batchSize = 20;                    // Mini-Batch 大小
    params.learningRate = 0.01;
    params.searchTime = 5000;
    params.regularizationStrength = 0.001;    // L2 正则化强度
    params.momentumFactor = 0.9;              // 动量因子
    params.maxIters = 10000;                  // 最大迭代次数
    params.shuffle = 1;                       // 打乱数据
    params.verbose = 1;                       // 输出训练日志

    // 开始训练 (使用 Mini-Batch SGD)
    optimize(params);

    // 评估准确率
    printf("Accuracy is %f\n", accuracy(net, trainingData, trainingClasses));

    // 进行预测
    forwardPass(net, trainingData);
    int* predictions = predict(net);
    // ... 使用 predictions ...
    free(predictions);

    // 保存网络到文件
    saveNetwork(net, "network.model");

    // 清理内存
    destroyNetwork(net);
    destroyDataSet(trainingData);
    destroyDataSet(trainingClasses);
    
    // 释放原始数据内存 (示例中手动分配的)
    for(int i=0; i<rows; i++) {
        free(training[i]);
        free(classes_target[i]);
    }
    free(training);
    free(classes_target);

    return 0;
}

3. 加载已保存的网络

若需使用之前训练好的模型：

// 从文件加载网络
Network* previousNet = readNetwork("network.model");

// ... 使用网络进行推理 ...

// 使用后销毁
destroyNetwork(previousNet);