LSR 004 - 标准库

基本信息

LSR 编号 004
标题标准库
作者 Ziyang-Bai
状态草案
类型标准规范
创建日期 02-04-2026
归属项目通用

摘要

定义 Lamina 标准库（std）的模块结构、导入与调用规则、数学核心 API 和错误模型。

技术规范

1. 设计目标

统一、稳定、可组合的标准 API
对齐 LSR-000 的静态强类型与单位系统
覆盖数学核心能力（数值、线代、统计、随机、单位）
同名函数跨平台语义一致

2. 命名空间与模块结构

标准库顶级命名空间固定为 std。

模块	作用域	说明
`std.math`	通用数学	初等函数、三角函数、指数对数、舍入、数值辅助
`std.linalg`	线性代数	矩阵分解、求解、逆、行列式、特征值
`std.stats`	统计	描述统计、分位数、协方差、相关系数
`std.random`	随机数	伪随机引擎、分布采样、种子控制
`std.units`	单位工具	单位转换辅助与量纲工具函数
`std.constants`	常量集	统一暴露 LSR-002 常量
`std.io`	基础 I/O	文本输入输出与格式化

规则：

模块名称与路径大小写敏感
std 根命名空间保留；用户模块定义在非 std 命名空间

3. 导入与库调用约定

3.1 导入语法

import std.math
import std.linalg as la

use std.math.{sin, cos, pi}
use std.constants.{G as GRAVITY}

规则：

import a.b 绑定模块对象到当前作用域（默认名为末段标识符）
import a.b as x 使用别名绑定模块对象
use a.b.{x, y as z} 导入符号；若与当前作用域重名则编译报错

3.2 调用约定

let y = math.sin(math.pi / 2)
let detA = la.det(A)

规则：

模块函数调用统一使用 module.func(args...)
对 use 导入的符号可直接调用
标准库函数以纯函数语义为默认，参数只读

3.3 `.` 规则

. 用于命名空间路径与成员访问；import/use 中路径与符号选择均使用 .。

import std.math
use std.math.{sin, cos}

let a = math.sin(pi / 2)   # '.' 成员访问
let b = sin(pi / 2)        # 通过 use 导入后可直接访问

规则：

import a.b / use a.b.{...} 中的 . 表示命名空间路径
运行期表达式的 a.b 表示成员访问（模块对象、表、对象）

4. 数学系统

4.1 `std.math`

函数	签名	说明
`abs`	`func abs(x num) -> num`	绝对值
`sqrt`	`func sqrt(x num) -> num`	平方根
`pow`	`func pow(x num, y num) -> num`	幂
`exp`	`func exp(x num) -> num`	指数函数
`log`	`func log(x num) -> num`	自然对数
`log10`	`func log10(x num) -> num`	常用对数
`sin`	`func sin(x num) -> num`	正弦
`cos`	`func cos(x num) -> num`	余弦
`tan`	`func tan(x num) -> num`	正切
`asin`	`func asin(x num) -> num`	反正弦
`acos`	`func acos(x num) -> num`	反余弦
`atan`	`func atan(x num) -> num`	反正切
`floor`	`func floor(x num) -> num`	向下取整
`ceil`	`func ceil(x num) -> num`	向上取整
`round`	`func round(x num) -> num`	四舍五入
`clamp`	`func clamp(x num, lo num, hi num) -> num`	截断到区间

常量：pi, e, phi。

4.2 `std.linalg`

函数	签名	说明
`shape`	`func shape(A matrix) -> vector<int>`	返回维度 `[rows, cols]`
`transpose`	`func transpose(A matrix) -> matrix`	非共轭转置
`adjoint`	`func adjoint(A matrix) -> matrix`	共轭转置
`det`	`func det(A matrix) -> num`	行列式（方阵）
`inv`	`func inv(A matrix) -> matrix`	矩阵逆（方阵）
`rank`	`func rank(A matrix) -> int`	矩阵秩
`trace`	`func trace(A matrix) -> num`	迹
`solve_left`	`func solve_left(A matrix, B matrix) -> matrix`	解 `A X = B`
`solve_right`	`func solve_right(B matrix, A matrix) -> matrix`	解 `X A = B`
`eig`	`func eig(A matrix) -> table<text, matrix>`	特征值/特征向量
`svd`	`func svd(A matrix) -> table<text, matrix>`	奇异值分解

语义对齐：

solve_left(A, B) 与运算符 A \\ B 等价
solve_right(B, A) 与运算符 B / A（矩阵语义）等价

4.3 `std.stats`

函数	签名	说明
`mean`	`func mean(x vector<num>) -> num`	均值
`median`	`func median(x vector<num>) -> num`	中位数
`var`	`func var(x vector<num>) -> num`	方差
`std`	`func std(x vector<num>) -> num`	标准差
`quantile`	`func quantile(x vector<num>, q num) -> num`	分位数
`cov`	`func cov(x vector<num>, y vector<num>) -> num`	协方差
`corr`	`func corr(x vector<num>, y vector<num>) -> num`	相关系数

4.4 `std.random`

函数	签名	说明
`seed`	`func seed(s int) -> bool`	设置随机种子
`rand`	`func rand() -> num`	`U(0,1)` 采样
`randint`	`func randint(lo int, hi int) -> int`	区间整数采样
`normal`	`func normal(mu num, sigma num) -> num`	正态采样
`choice`	`func choice(x vector<num>) -> num`	离散采样

4.5 `std.units`

函数	签名	说明
`convert`	`func convert(x num, u text) -> num`	将数值转换到单位字符串 `u`
`strip`	`func strip(x num) -> num`	等价于 `x as num`（见 LSR-008）
`is_dimensionless`	`func is_dimensionless(x num) -> bool`	是否无量纲

规则：strip 只是函数入口，语义以 LSR-008 为准。

5. 常量系统

std.constants 暴露 LSR-002 定义的常量集合
常量以只读绑定导出
常量单位必须与 LSR-000 量纲系统一致

5.1 用户自定义常量

用户可在模块内定义常量：

module user.constants {
    const G_MARS = 3.72076<m/s^2>
    const TAU = 2 * pi
}

规则：

const 必须在声明时初始化
初始化表达式必须可在编译期求值
常量为只读绑定；编译期校验覆盖重定义与写入

5.2 用户自定义单位

用户可在模块内定义单位：

module user.units {
    unit score
    unit token

    unit km = 1000<m>
    unit min = 60<s>
    unit knot = 0.514444<m/s>
    unit level = 100<score>
}

规则：

unit 声明进入当前命名空间
允许定义抽象基单位（不归约到 SI）
派生单位必须可归约到已知单位（SI 或抽象基单位）
可通过 import/use 跨模块复用

示例：

use std.constants.{G, C, EARTH_GRAVITY}
let v = EARTH_GRAVITY * 2<s>

6. 错误模型

标准库错误采用可诊断错误码，至少覆盖：

DomainError：输入超出定义域（如 log(-1)）
DimensionMismatch：线代/广播维度不匹配
SingularMatrix：矩阵奇异或线性系统奇异
EmptyInput：统计函数输入为空
InvalidArgument：参数类型或取值非法

7. 性能与确定性约束

同版本标准库在同一输入下必须给出可重现结果（随机模块除外）
std.random 在固定种子下必须可重放
线性代数实现允许后端差异，但数值误差须在文档化容差内

8. 版本与稳定性

std 下 API 采用语义化版本管理
对外函数签名变更属于破坏性变更，需提升主版本
新增函数保持向后兼容调用行为；既有函数语义保持稳定

9. 示例

import std.math
import std.linalg as la
use std.stats.{mean, std}
use std.units.{strip}

let A = mat[2,1;1,3]
let B = mat[1;2]
let X = A \\ B

let angle = math.pi / 4
let s = math.sin(angle)

let speed = 36<km/h>
let raw_si = strip(speed as <m/s>)

let xs = vec[1,2,3,4,5]
let m = mean(xs)
let sd = std(xs)

10. 与其他 LSR 的关系

LSR-000：语言核心语法与运算符语义
LSR-002：标准常量定义来源
LSR-003：标准库可由扩展模块补充实现
LSR-008：as num 量纲剥离语义来源