LSR 004 - 标准库 ================================================================================ 基本信息 -------------------------------------------------------------------------------- - LSR 编号 004 - 标题 标准库 - 作者 Ziyang-Bai - 状态 草案 - 类型 标准规范 - 创建日期 02-04-2026 - 归属项目 通用 摘要 -------------------------------------------------------------------------------- 定义 Lamina 标准库（``std`` ）的模块结构、导入与调用规则、数学核心 API 和错误模型。 技术规范 -------------------------------------------------------------------------------- 1. 设计目标 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 统一、稳定、可组合的标准 API - 对齐 LSR-000 的静态强类型与单位系统 - 覆盖数学核心能力（数值、线代、统计、随机、单位） - 同名函数跨平台语义一致 2. 命名空间与模块结构 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 标准库顶级命名空间固定为 ``std``。 .. list-table:: :header-rows: 1 * - 模块 - 作用域 - 说明 * - ``std.math`` - 通用数学 - 初等函数、三角函数、指数对数、舍入、数值辅助 * - ``std.linalg`` - 线性代数 - 矩阵分解、求解、逆、行列式、特征值 * - ``std.stats`` - 统计 - 描述统计、分位数、协方差、相关系数 * - ``std.random`` - 随机数 - 伪随机引擎、分布采样、种子控制 * - ``std.units`` - 单位工具 - 单位转换辅助与量纲工具函数 * - ``std.constants`` - 常量集 - 统一暴露 LSR-002 常量 * - ``std.io`` - 基础 I/O - 文本输入输出与格式化 规则： - 模块名称与路径大小写敏感 - ``std`` 根命名空间保留；用户模块定义在非 ``std`` 命名空间 3. 导入与库调用约定 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3.1 导入语法 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: text 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 调用约定 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: text let y = math.sin(math.pi / 2) let detA = la.det(A) 规则： - 模块函数调用统一使用 ``module.func(args...)`` - 对 ``use`` 导入的符号可直接调用 - 标准库函数以纯函数语义为默认，参数只读 3.3 ``.`` 规则 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``.`` 用于命名空间路径与成员访问；``import``/``use`` 中路径与符号选择均使用 ``.``。 .. code-block:: text 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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - 函数 - 签名 - 说明 * - ``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`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - 函数 - 签名 - 说明 * - ``shape`` - ``func shape(A matrix) -> vector`` - 返回维度 ``[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`` - 特征值/特征向量 * - ``svd`` - ``func svd(A matrix) -> table`` - 奇异值分解 语义对齐： - ``solve_left(A, B)`` 与运算符 ``A \\ B`` 等价 - ``solve_right(B, A)`` 与运算符 ``B / A`` （矩阵语义）等价 4.3 ``std.stats`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - 函数 - 签名 - 说明 * - ``mean`` - ``func mean(x vector) -> num`` - 均值 * - ``median`` - ``func median(x vector) -> num`` - 中位数 * - ``var`` - ``func var(x vector) -> num`` - 方差 * - ``std`` - ``func std(x vector) -> num`` - 标准差 * - ``quantile`` - ``func quantile(x vector, q num) -> num`` - 分位数 * - ``cov`` - ``func cov(x vector, y vector) -> num`` - 协方差 * - ``corr`` - ``func corr(x vector, y vector) -> num`` - 相关系数 4.4 ``std.random`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - 函数 - 签名 - 说明 * - ``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`` - 离散采样 4.5 ``std.units`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 * - 函数 - 签名 - 说明 * - ``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 用户自定义常量 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 用户可在模块内定义常量： .. code-block:: text module user.constants { const G_MARS = 3.72076 const TAU = 2 * pi } 规则： - ``const`` 必须在声明时初始化 - 初始化表达式必须可在编译期求值 - 常量为只读绑定；编译期校验覆盖重定义与写入 5.2 用户自定义单位 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 用户可在模块内定义单位： .. code-block:: text module user.units { unit score unit token unit km = 1000 unit min = 60 unit knot = 0.514444 unit level = 100 } 规则： - ``unit`` 声明进入当前命名空间 - 允许定义抽象基单位（不归约到 SI） - 派生单位必须可归约到已知单位（SI 或抽象基单位） - 可通过 ``import``/``use`` 跨模块复用 示例： .. code-block:: text use std.constants.{G, C, EARTH_GRAVITY} let v = EARTH_GRAVITY * 2 6. 错误模型 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 标准库错误采用可诊断错误码，至少覆盖： - ``DomainError`` ：输入超出定义域（如 ``log(-1)`` ） - ``DimensionMismatch`` ：线代/广播维度不匹配 - ``SingularMatrix`` ：矩阵奇异或线性系统奇异 - ``EmptyInput`` ：统计函数输入为空 - ``InvalidArgument`` ：参数类型或取值非法 7. 性能与确定性约束 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 同版本标准库在同一输入下必须给出可重现结果（随机模块除外） - ``std.random`` 在固定种子下必须可重放 - 线性代数实现允许后端差异，但数值误差须在文档化容差内 8. 版本与稳定性 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``std`` 下 API 采用语义化版本管理 - 对外函数签名变更属于破坏性变更，需提升主版本 - 新增函数保持向后兼容调用行为；既有函数语义保持稳定 9. 示例 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: text 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 let raw_si = strip(speed as ) 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`` 量纲剥离语义来源 - LSR-009：多个同类标准库结果使用 ``set`` 表示 - LSR-010：``std.math`` 复数常量与复数函数语义来源