LSR 004 - 标准库

基本信息

• LSR 编号 004

• 标题 标准库

• 作者 Ziyang-Bai

• 状态 草案

• 类型 标准规范

• 创建日期 02-04-2026

• 归属项目 通用

摘要

定义 Lamina 标准库（std ）的模块结构、导入与调用规则、数学核心 API 和错误模型；扩展模块可补充标准库实现 [3]。

技术规范

1. 设计目标

• 统一、稳定、可组合的标准 API

• 对齐 LSR-000 [1] 的静态强类型与单位系统

• 覆盖数学核心能力（数值、线代、统计、随机、单位）

• 同名函数跨平台语义一致

2. 命名空间与模块结构

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

模块	作用域	说明
std.math	通用数学	初等函数、三角函数、指数对数、舍入、数值辅助
std.cas	符号数学	数学等价、结构查询、保域化简、符号代入与重写，接口见 LSR-016 [7]
std.linalg	线性代数	矩阵分解、求解、逆、行列式、特征值
std.stats	统计	描述统计、分位数、协方差、相关系数
std.random	随机数	伪随机引擎、分布采样、种子控制
std.units	单位工具	单位转换辅助与量纲工具函数
std.constants	常量集	统一暴露 LSR-002 [2] 常量
std.io	基础 I/O	文本输入输出与格式化
std.mathematics_error	数学错误	固定内建 MathError 的构造、字段与终止函数，接口见 LSR-018 [8]

规则：

• 模块名称与路径大小写敏感

• 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 导入的符号可直接调用

• 标准库函数以纯函数语义为默认，参数只读

• 参数绑定、具名实参与源码顺序求值遵循 LSR-000 [1]；绑定完成后检查值约束

• 容器保持值语义；参数只读不代表返回值与输入具有可观察的共享身份

3.3 . 规则

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

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

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

规则：

• import a.b / use a.b.{...} 中的 . 表示命名空间路径

• 运行期表达式的 a.b 表示成员访问（模块对象、表、对象）

4. 数学系统

数学基本静态类型统一为 num，包括精确数、符号表达式、关系与近似值； vector、matrix、set 保留结构类型，数学元素均为 num。 int、frac、real、complex 是整数、有理数、实标量、复标量值约束， 并非独立基本数学类型。-> int、vector<int> 分别约束结果或各元素， 其基本类型仍为 num、vector<num>。这些约束参与调用/返回检查， 不能使基本签名和参数个数相同的函数仅按值约束静态分派。 静态可证明时提前检查；确定违反约束报告 DomainError 或 InvalidArgument， 仍无法确定报告 Inconclusive。整数索引、尺寸、随机种子等还必须可具体求值， 不能只凭底层小整数表示或符号整数性决定可用性。 函数值的参数和值返回仍检查完整约束及量纲契约；不能因底层 num 相同而放宽受约束参数。

数学 API 默认精确、保域，支持的数学运算可返回未求值式，不自动把精确输入改成浮点数。 在已声明数学调用的支持域内，精确算法尚不能完成或成立条件未决时保留调用； 确定无定义的运算报告错误。普通副作用函数、未绑定名称及参数错误不得借此自动延迟。 sym 默认复数标量，实性、正性和整数性由假设或约束提供。 复数平方根、对数和非整数幂采用单值主值；全部根和解由集合求解接口表达。 复数没有无条件的实数顺序；取整、排序、分位数和区间判定须满足相应实数域及顺序条件。

默认化简保留原定义域。x/x、0*(1/x) 的消去须有局部非零及定义性前提； 显式形式代数入口见 std.cas.simplify_formal [7]，不得把它当成普通数学调用的默认策略。

4.1 std.math

std.math 的复数常量与复数函数语义见 LSR-010 [6]。pi、e、phi 是精确数学常量，不是隐藏的机器浮点近似。

函数	签名	说明
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 real) -> int	向下取整
ceil	func ceil(x real) -> int	向上取整
round	func round(x real) -> int	舍入到最近整数，同距时远离零
clamp	func clamp(x real, lo real, hi real) -> real	截断到有序实区间，要求 lo <= hi
approximate	func approximate(value num, precision int) -> num	显式请求目标十进制有效位数；两个参数均必需

approximate 是精确数学进入近似计算的显式入口；通过 use 导入后可直接调用。 precision 必须是可具体求值的正整数，表示目标十进制有效位数， 不是字节数、二进制位数、显示小数位数或量纲。不提供省略精度的一参形式； 下例的 100 是显式实参，不是默认参数。具名实参采用普通调用规则：

use std.math.{approximate}

let third = approximate(1/3, precision=100)

成功时按请求工作精度计算支持的可求值部分，保留近似标记和目标工作精度； 未知符号部分仍保留，不用默认值补齐。不能在所请求精度下完成时必须报告错误， 不得以机器双精度冒充高精度成功。不保证正确舍入或认证误差界， 误差估计与认证接口是可选扩展。已有近似输入提高工作精度不会恢复已丢失的信息。

包含近似操作数的该次数学运算采用参与近似值中的最高工作精度， 其可求值的精确子项按需要数值化；尚未绑定或暂不可求值的符号部分保留。 其他未参与该次运算的精确值保持原值。精确/近似比较无损比较现有存储数值， 不先舍入，也不引入容差；结论仅关于表示值，不把显示小数重新解析成原式的精确值。

use std.math.{approximate, sqrt}

let a = approximate(sqrt(2), precision=100)
let mixed = a + sqrt(3)

在支持的可求值域内，mixed 按 100 位十进制工作精度近似求值； 表达式中的 sqrt(3) 按需要参与该次计算，既有精确值不被原地改写。

approximate 对数学向量/矩阵按相同规则逐元素作用，保留形状及静态量纲； 它不把数学容器变为普通数组，也不改变单位。其对应重载的参数和结果基本类型均保持 vector<num> 或 matrix<num>。

func approximate(value vector<num>, precision int) -> vector<num>
func approximate(value matrix<num>, precision int) -> matrix<num>

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) -> (matrix, matrix)	按顺序返回（特征向量矩阵，特征值对角矩阵）
svd	func svd(A matrix) -> (matrix, matrix, matrix)	按顺序返回 (U, S, V)，满足 A = U S V*，其中 V* 为共轭转置

语义对齐：

• solve_left(A, B) 与运算符 A \ B 等价

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

• eig 与 svd 的各分量按固定位置组成单个元组 [9]

• 精确输入默认走精确数学语义，不能因选用数值后端而隐式调用 approximate； 只能近似求解的接口须明确要求近似输入或显式近似请求，不能静默降精度

• 奇异性或分支条件未决时保留所支持的数学调用；已证明奇异时报告 SingularMatrix

import std.linalg

let (eigenvectors, eigenvalues) = linalg.eig(A)
let (U, S, V) = linalg.svd(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	离散采样

随机引擎是有状态的例外，不适用纯函数默认规则。种子和 randint 端点须为可具体求值的整数； 要求 lo <= hi，整数采样结果是精确整数。rand 与 normal 是显式分布采样入口， 返回有限精度样本时须保留近似标记及工作精度，并公布采样精度； 它们不隐式求值或近似符号参数。normal 要求可求值实参数且 sigma > 0。

4.5 std.units

函数	签名	说明
as	x as <unit>	核心静态单位转换语法，不是接收运行期单位文本的函数
strip	func strip(x num) -> num	等价于 x as num （见 LSR-008 [4]）
is_dimensionless	func is_dimensionless(x num) -> bool	是否无量纲

核心单位转换由 as <unit> 静态检查源和目标量纲，只允许同量纲转换； 换算因子是精确值时保持精确。strip 是 as num 的函数入口， 先转换为 SI 基准量值再移除单位签名，语义以 LSR-008 [4] 为准。is_dimensionless 查询静态量纲， 不根据运行期裸数猜测原单位；已剥离的裸数无需也不能恢复原量纲信息。

运行期单位文本解析和异量纲动态包装属于可选扩展，不是核心 convert(x, text) 契约。 扩展须显式携带单位元数据、声明检查与错误规则，不能把同一个静态 num 容器 解释为任意量纲的集合。核心异量纲组合使用静态元组 [9]。

4.6 std.cas

std.cas 的数学输入与结果使用 num，不另设表达式基本类型。 substitute、match_expr、rewrite、固定内建 rule、 保域 simplify 和显式 simplify_formal 由 LSR-016 [7] 定义。 未解释符号函数必须显式通过 symbolic_function(name text, arity int) -> func 构造，返回固定参数个数、参数和结果均为 num 的函数； 普通未绑定函数名仍是名称错误。

num 和数学容器的 ==/!= 构造数学关系；逐元素比较生成关系值元素。 布尔结构查询使用 std.cas.same_structure，内部集合去重、哈希和匹配也使用结构规则， 不调用构造关系的相等运算或有限证明。 数学等价 === 和 std.cas.equivalent 返回固定状态 std.cas.Equivalence： cas.Equivalent、cas.Different、cas.Unknown；这些状态的 == 返回 bool。 Unknown 表示证明未决，不能作为 Different；预算/规则通过显式查询参数配置， 不得依赖无作用域的可变全局设置。取消和运行时故障仍以错误传播。

4.7 区间与整数范围

数学区间默认为实数集合，整数端点不把它改为整数集合，构造与成员语义见 LSR-017 [10]。 端点倒置时区间为空；端点相等时仅双闭区间为单点，其余为空。 端点顺序未知时保留符号区间，代入后继续按同一规则判定。 普通端点和符号端点没有不同的成员域或值语义。 端点必须满足实数值约束；实性未决报告 Inconclusive，而不是猜测成员域。 区间整体 ==/!= 构造数学关系，布尔结构查询使用 same_structure。 整数 range 与实区间独立，其步进和取值须可具体计算； 不得从端点的内部表示推断 interval<int>。

5. 常量系统

• std.constants 暴露 LSR-002 [2] 定义的常量集合

• 常量以只读绑定导出

• 常量单位必须与 LSR-000 [1] 量纲系统一致

• 精确、测量和参考常量按 LSR-002 [2] 分类；有限测量/参考数据不得标为物理精确值

5.1 用户自定义常量

用户可在 user/constants.lm 中定义模型采用的常量：

use std.math.{pi}

const G_MARS = 3.72076<m/s^2>
const TAU = 2 * pi

规则：

• const 必须在声明时初始化

• 初始化表达式必须可在编译期求值

• 常量为只读绑定；编译期校验覆盖重定义与写入

5.2 用户自定义单位

用户可在 user/units.lm 中定义单位：

unit score
unit token

unit km = 1000<m>
unit min = 60<s>
unit knot = (1852/3600)<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 ：输入确定超出所用运算的定义域（如 1/0；复主值 log(-1) 不属此例）

• DimensionMismatch ：线代/广播维度不匹配

• SingularMatrix ：矩阵奇异或线性系统奇异

• EmptyInput ：统计函数输入为空

• InvalidArgument ：参数类型或取值非法

• Inconclusive ：必要的数域、值约束或控制流判定仍未决

• NumericalFailure ：近似计算或机器转换无法满足精度/范围契约

• ResourceLimit、Cancelled ：计算资源耗尽或取消

普通数学函数直接返回签名声明的结果值。计算失败通过 LSR-018 [8] 的 raise 与故障传播机制报告；错误类别、操作和消息必须保留，不以零、空结果或低精度结果冒充成功。 if/while 接受布尔值或数学关系，关系自动判真，未知报告 Inconclusive； 数字不能作真假转换。普通布尔逻辑短路，关系上的逻辑运算构造表达式， 程序控制流仅执行已确定分支，不把副作用隐式符号化。 求解接口在证明解集为空时返回空集合，在完整解集待定时遵循 LSR-013 [5]， 不得把算法未完成伪装为无解。可保留的未求值数学结果与错误、三态证明未决是不同契约。

7. 性能与确定性约束

• 同版本标准库在同一输入下必须给出可重现结果（随机模块除外）

• std.random 在固定种子下必须可重放

• 线性代数可选择不同后端，但不得改变默认精确语义；显式近似结果须满足声明的工作精度， 不以误差容差改写数学 ==、=== 或结构查询

8. 版本与稳定性

• std 下 API 采用语义化版本管理

• 对外函数签名变更属于破坏性变更，需提升主版本

• 新增函数保持向后兼容调用行为；既有函数语义保持稳定

• 无序、按相等关系去重的同类数学结果使用集合 [5]；按固定位置区分的结果使用元组 [9]，需要顺序或重数的结果使用向量或接口定义的组合

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. 引用

[1] (1,2,3)

LSR-000 - Lamina 核心语言规范（草案） - 语言核心语法与运算符语义

[2] (1,2,3)

LSR-002 - 标准常量规范 - 标准常量定义来源

[3]

LSR-003 - Lamina C 扩展与插件规范 - 标准库可由扩展模块补充实现

[4] (1,2)

LSR-008 - 量纲剥离（Unit Stripping）规范 - as num 量纲剥离语义来源

[5] (1,2)

LSR-013 - 集合类型规范 - 有限集合与数学解集返回约定

[6]

LSR-010 - 虚数单位与复数规范 - std.math 复数常量与复数函数语义来源

[7] (1,2,3)

LSR-016 - 数学值与符号操作规范 - std.cas 的结构、等价、化简与符号操作

[8] (1,2)

LSR-018 - Never 底类型与 raise 终止效应规范 - 数学错误值与故障传播

[9] (1,2,3)

LSR-012 - 元组类型规范 - 按固定位置组合与解构多个结果

[10]

LSR-017 - 区间类型规范 - 默认实数区间及符号端点