From 9e1c3bd9c003b73d4a00ee8a03b2f17fab70ae83 Mon Sep 17 00:00:00 2001 From: Reiase Date: Mon, 10 Aug 2026 00:24:51 +0800 Subject: [PATCH] docs: polish design documentation and add numerical analysis + workspace pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add numerical-analysis.{en,zh}.md covering the interactive IEEE floating-point format analysis (format layout, bit decode, dynamic range, quantization error, operation range impact) and its place in the analysis architecture - Add exploration/workspace.{en,zh}.md documenting the workbench workspace modes (point/batch/evidence/numeric lens), shared config surface, and invariants - Add WORKSPACE buffer role semantics to PortablePlanIR contract (conservative upper bound → target-specific workspace replacement) - Fix broken FrozenDict import path in providers.md (synthesizer → schema) - Add "Not yet callable" note to ExplorationSession facade in modules.md - Add cross-references between numerical-analysis, workspace, and related pages - Update reading lists and mkdocs navigation --- docs/design/index.en.md | 1 + docs/design/index.zh.md | 1 + docs/design/ir/planning-execution.en.md | 10 +++++ docs/design/ir/planning-execution.zh.md | 10 +++++ docs/design/modules.en.md | 3 ++ docs/design/modules.zh.md | 3 ++ docs/design/numerical-analysis.en.md | 52 +++++++++++++++++++++++++ docs/design/numerical-analysis.zh.md | 52 +++++++++++++++++++++++++ docs/design/performance/providers.en.md | 2 +- docs/design/performance/providers.zh.md | 2 +- docs/exploration/index.en.md | 2 +- docs/exploration/index.zh.md | 2 +- docs/exploration/workspace.en.md | 49 +++++++++++++++++++++++ docs/exploration/workspace.zh.md | 49 +++++++++++++++++++++++ mkdocs.yml | 4 ++ 15 files changed, 238 insertions(+), 4 deletions(-) create mode 100644 docs/design/numerical-analysis.en.md create mode 100644 docs/design/numerical-analysis.zh.md create mode 100644 docs/exploration/workspace.en.md create mode 100644 docs/exploration/workspace.zh.md diff --git a/docs/design/index.en.md b/docs/design/index.en.md index 0691d13..189b1f2 100644 --- a/docs/design/index.en.md +++ b/docs/design/index.en.md @@ -132,6 +132,7 @@ First-class architecture blueprints, target/resource binding, concrete schedulin - [Timeline staging path](timeline-path.md) separates command plans, predictive timelines, prescriptive timing, and LPU backend evolution. - [Golden derivation walkthrough](walkthrough.md) follows one Transformer fragment through every representation. - [Analysis module architecture](modules.md) assigns Python ownership and extension boundaries. +- [Floating-point numerical analysis](numerical-analysis.md) defines the interactive numerical format analysis view and its boundary. - [Formal representation reference](ir/index.md) defines semantic contracts. - [Analysis and transformation reference](passes/index.md) defines verified transactions. diff --git a/docs/design/index.zh.md b/docs/design/index.zh.md index dcb2540..246c565 100644 --- a/docs/design/index.zh.md +++ b/docs/design/index.zh.md @@ -132,6 +132,7 @@ First-class architecture blueprint、target/resource binding、concrete scheduli - [Timeline 阶段路径](timeline-path.md)区分 command plan、预测时间线、强制时序与 LPU backend 演进。 - [完整推导示例](walkthrough.md)展示一个 Transformer fragment 穿过所有 representation。 - [分析模块架构](modules.md)定义 Python ownership 与 extension boundary。 +- [浮点数数值分析](numerical-analysis.md)定义交互式数值格式分析视图及其边界。 - [形式化表示 reference](ir/index.md)定义 semantic contract。 - [分析与变换 reference](passes/index.md)定义 verified transaction。 diff --git a/docs/design/ir/planning-execution.en.md b/docs/design/ir/planning-execution.en.md index c5881d0..6e9a9ef 100644 --- a/docs/design/ir/planning-execution.en.md +++ b/docs/design/ir/planning-execution.en.md @@ -26,6 +26,16 @@ Exact operations, read/write bytes, message bytes, reuse, and arithmetic intensi Portable plans cannot contain physical implementation IDs, vendor libraries, physical devices, routes, queues, engines, memory banks, addresses, target-derived latency, or execution timestamps. +### Abstract workspace and conservative bounds + +The `WORKSPACE` buffer role expresses abstract working memory (transient scratch) at the portable layer. It is a capacity and legality constraint, not a timing fact: + +- before an implementation is selected, a workspace carries only a defensible conservative upper bound (for example, the unfused score-materialization bound of attention), and the bound's semantic must be recorded; +- target binding must replace the conservative bound with implementation-specific workspace (fused-attention scratch, kernel workspace, paged intermediates), and the resulting allocation must never exceed target memory capacity under any legal execution; +- a conservative bound is not a precise demand: its derivation must be traceable to a semantic reason, and replacement must preserve workload facts unchanged. + +The current inference slice already implements this role: `PlanTransformerInferencePass` emits a `workspace-upper-bound` buffer with role `WORKSPACE`, storage `TRANSIENT`, and semantic `block_working_upper_bound`. Implementation-specific workspace replacement is an obligation of the portable-to-concrete gate. The phase-plan semantics on the inference side are described in [Inference Planning and Serving Simulation](../../modeling/inference.md). + ### Verification The verifier checks task-reference integrity, DAG closure, buffer lifecycle consistency, resource-requirement validity, exact nonnegative work facts, objective and constraint identity, source lineage, and the absence of target-bound fields. diff --git a/docs/design/ir/planning-execution.zh.md b/docs/design/ir/planning-execution.zh.md index c7c0629..a34c9e6 100644 --- a/docs/design/ir/planning-execution.zh.md +++ b/docs/design/ir/planning-execution.zh.md @@ -26,6 +26,16 @@ PortablePlanIR Portable plan 不能包含 physical implementation ID、vendor library、physical device、route、queue、engine、memory bank、address、target-derived latency 或 execution timestamp。 +### 抽象工作空间与保守上界 + +`WORKSPACE` buffer role 表达 portable 层的抽象工作内存（transient scratch）。它是容量与 legality 约束，不是 timing fact： + +- 未选定实现时，workspace 只能携带可辩护的保守上界（例如 attention 未融合 score materialization 的容量上界），并记录该 bound 的 semantic； +- Target binding 必须用 implementation-specific workspace（fused-attention scratch、kernel workspace、paged intermediate 等）替换保守上界，且替换后的分配在任意合法执行下都不得超出 target memory 容量； +- 保守 bound 不是精确需求：它的推导必须可追溯到语义原因，替换必须保持 workload facts 不变。 + +当前 inference slice 已实现该角色：`PlanTransformerInferencePass` 发出 `workspace-upper-bound` buffer（role=`WORKSPACE`、storage=`TRANSIENT`、semantic=`block_working_upper_bound`）。Implementation-specific workspace 替换属于 portable-to-concrete gate 的 obligation。推理侧的 phase-plan 语义见[推理规划与 Serving 仿真](../../modeling/inference.md)。 + ### Verification Verifier 检查 task reference integrity、DAG closure、buffer lifecycle consistency、resource-requirement validity、exact nonnegative work fact、objective/constraint identity、source lineage，以及 target-bound field absence。 diff --git a/docs/design/modules.en.md b/docs/design/modules.en.md index 2354e46..3b9c894 100644 --- a/docs/design/modules.en.md +++ b/docs/design/modules.en.md @@ -6,6 +6,9 @@ Modules follow hardware-experiment ownership, not merely source-file convenience The future public facade should expose architecture exploration rather than an IR pipeline: +!!! note "Not yet callable" + `ExplorationSession` and `blueprinting.explore()` are design targets, not implemented in the current repository. The code below is illustrative pseudocode. + ```python experiment = ExplorationSession( workloads=WorkloadSuite(...), diff --git a/docs/design/modules.zh.md b/docs/design/modules.zh.md index 77e70e8..40fe92e 100644 --- a/docs/design/modules.zh.md +++ b/docs/design/modules.zh.md @@ -6,6 +6,9 @@ 未来 public facade 应暴露 architecture exploration，而不是一条 IR pipeline： +!!! note "当前不可调用" + `ExplorationSession` 与 `blueprinting.explore()` 是设计目标，当前仓库尚未实现。以下代码是说明性伪代码。 + ```python experiment = ExplorationSession( workloads=WorkloadSuite(...), diff --git a/docs/design/numerical-analysis.en.md b/docs/design/numerical-analysis.en.md new file mode 100644 index 0000000..84dd11a --- /dev/null +++ b/docs/design/numerical-analysis.en.md @@ -0,0 +1,52 @@ +# Floating-Point Numerical Analysis + +Blueprinting's interactive floating-point analysis is a **numerical-fact exploration surface** in the workspace. It decodes IEEE-style binary floating-point formats, exposes dynamic range and representable values, and quantifies quantization and overflow/underflow risk for candidate datatypes. It is a presentation analysis view — it predicts neither execution time nor hardware behavior, and it does not define workload semantics. + +## Scope and motivation + +Datatype is a first-class workload fact: `WorkloadFacts` and plan buffers carry exact datatype and bytes-per-element, and Transformer derivation treats precision as a semantic input (see [workload model](../modeling/workload.md)). Before committing a blueprint or mapping to a datatype (bf16 vs fp16 vs fp8), an architect needs numerical questions answered: + +- what the format actually represents (dynamic range, subnormal region, Inf/NaN); +- how large the nearest-value quantization error is at the magnitudes the workload produces; +- which operations (add, subtract, multiply, divide) risk underflow or overflow at the format's limits. + +The floating-point panel answers these questions interactively, for standard formats and arbitrary custom layouts. + +## Analysis surface + +The panel exposes five connected views over one selected format. + +### Format layout comparison + +Standard presets — `fp32`, `tf32`, `bf16`, `fp16`, `fp8(E5M2)`, `fp8(E4M3)`, `fp4(E2M1)` — plus a custom format defined by sign bit (optional), exponent bits (`2..8`), and mantissa bits (`0..23`). The layout chart compares sign/exponent/mantissa widths across formats. + +### Bit-level decoding + +A bit editor decodes one concrete pattern with IEEE zero/subnormal/special handling: all-zero exponent with zero fraction is zero; all-zero exponent with nonzero fraction is subnormal; all-ones exponent with zero fraction is infinity; all-ones exponent with nonzero fraction is NaN. The decode shows category, raw exponent, significand, and value. + +### Dynamic range and representable values + +For the selected format the panel reports bias, min normal, min subnormal, and max finite. The representable-values view enumerates finite values within the observation window and marks normal (blue) and subnormal (red) regions. + +### Quantization error + +The nearest-value quantization error curve samples a dense input range and reports the absolute error to the nearest representable value, exposing the format's precision at the magnitudes of interest. + +### Operation range impact + +A Cartesian sample over up to 64 downsampled representable values runs `A + B`, `A − B`, `A × B`, and `A ÷ B`, and counts results that stay normal, become subnormal, underflow to zero, or overflow to Inf/NaN. This is numerical range analysis, not hardware execution time. + +## Place in the analysis architecture + +- The analysis functions are pure and deterministic; they live in `src/blueprinting/workbench/float_analysis.py`, with value enumeration in `src/blueprinting/fp/`. +- The panel does not consume `ModelIR`, `PortablePlanIR`, or any canonical IR. It is an independent interactive surface, not a derived view of a canonical plan. +- It produces no cost estimates, so it is not a cost provider and never enters the evidence-resolution path. +- Interactive enumeration is intentionally bounded to formats with exponent + mantissa bits ≤ 12 to keep the UI responsive. + +## Current boundary and next steps + +**Implemented:** the pure analysis functions, the workbench panel, and unit tests covering dynamic range, bit decoding, enumeration limits, and operation-impact completeness. + +**Not yet implemented:** coupling the analysis to workload datatype bindings, deriving per-operation quantization/overflow guardrails for a training or inference plan, and fp8 scaling-policy analysis. A future slice could expose numerical facts as an analysis addressed by a plan's datatype digest, without changing workload semantics. + +The workspace that hosts the panel is described in [Exploration Workspace](../exploration/workspace.md); project-wide implementation status is tracked in [Implementation Status](../project/status.md). diff --git a/docs/design/numerical-analysis.zh.md b/docs/design/numerical-analysis.zh.md new file mode 100644 index 0000000..8a2ec2b --- /dev/null +++ b/docs/design/numerical-analysis.zh.md @@ -0,0 +1,52 @@ +# 浮点数数值分析 + +Blueprinting 的交互式浮点分析是工作空间中的一块**数值事实探索面**。它解码 IEEE 风格二进制浮点格式，暴露动态范围与可表示值，并量化候选 datatype 的量化误差与溢出/下溢风险。它是 presentation analysis view——既不预测执行时间，也不描述硬件行为，更不定义 workload semantic。 + +## 范围与动机 + +Datatype 是 first-class workload fact：`WorkloadFacts` 与 plan buffer 携带精确 datatype 与 bytes-per-element，Transformer 推导把 precision 当作 semantic 输入（详见 [workload 模型](../modeling/workload.md)）。在把 blueprint 或 mapping 承诺给某个 datatype（bf16 vs fp16 vs fp8）之前，架构师需要回答数值问题： + +- 该格式实际能表示什么（动态范围、subnormal 区域、Inf/NaN）； +- 在 workload 关心的 magnitude 上，nearest-value 量化误差有多大； +- 加减乘除哪些运算在格式边界处会下溢或溢出。 + +浮点面板对标准格式与任意自定义布局交互式回答这些问题。 + +## 分析视图 + +面板围绕一个选定格式暴露五块相互关联的视图。 + +### 格式位宽对比 + +标准预设——`fp32`、`tf32`、`bf16`、`fp16`、`fp8(E5M2)`、`fp8(E4M3)`、`fp4(E2M1)`——以及由符号位（可选）、指数位（`2..8`）与尾数位（`0..23`）定义的自定义格式。位宽图跨格式比较 sign/exponent/mantissa 宽度。 + +### 位级解码 + +位编辑器按 IEEE zero/subnormal/special 规则解码一个具体 bit pattern：指数全 0 且 fraction 为 0 是 zero；指数全 0 且 fraction 非 0 是 subnormal；指数全 1 且 fraction 为 0 是 infinity；指数全 1 且 fraction 非 0 是 NaN。解码显示 category、raw exponent、significand 与 value。 + +### 动态范围与可表示值 + +面板报告选定格式的 bias、min normal、min subnormal 与 max finite。可表示值视图在观察窗口内枚举有限值，并标出 normal（蓝）与 subnormal（红）区域。 + +### 量化误差 + +Nearest-value 量化误差曲线对密集输入范围采样，报告到最近可表示值的绝对误差，暴露该格式在关注 magnitude 上的精度。 + +### 四则运算范围影响 + +对最多 64 个降采样的可表示值做笛卡尔组合，执行 `A + B`、`A − B`、`A × B`、`A ÷ B`，统计结果停留在 normal、落入 subnormal、下溢为零或溢出为 Inf/NaN 的计数。这是数值范围分析，不是硬件执行时间。 + +## 在分析架构中的位置 + +- 分析函数是纯函数且确定：位于 `src/blueprinting/workbench/float_analysis.py`，可表示值枚举位于 `src/blueprinting/fp/`。 +- 面板不消费 `ModelIR`、`PortablePlanIR` 或任何 canonical IR。它是独立交互面，不是 canonical plan 的 derived view。 +- 它不产生 cost estimate，因此不是 cost provider，也从不进入 evidence resolution 路径。 +- 交互式枚举被刻意限制在 exponent + mantissa ≤ 12 位的格式，以保持 UI 响应。 + +## 当前边界与后续 + +**已实现**：纯分析函数、workbench 面板，以及覆盖动态范围、位解码、枚举限制与运算影响完整性的单元测试。 + +**未实现**：与 workload datatype binding 联动、为 training/inference plan 推导 per-operation 量化/溢出 guardrail，以及 fp8 scaling-policy 分析。未来的 slice 可以把数值事实暴露为按 plan 的 datatype digest 寻址的 analysis，而不改变 workload semantic。 + +承载该面板的探索工作空间见[探索工作空间](../exploration/workspace.md)；全项目实现状态以[实现状态](../project/status.md)为准。 diff --git a/docs/design/performance/providers.en.md b/docs/design/performance/providers.en.md index 1745bb7..644ea6d 100644 --- a/docs/design/performance/providers.en.md +++ b/docs/design/performance/providers.en.md @@ -75,7 +75,7 @@ from blueprinting.analysis import ( SimulatorPerformanceImporter, TabularImportSpec, ) -from blueprinting.synthesizer.frozen import FrozenDict +from blueprinting.schema.frozen import FrozenDict spec = TabularImportSpec( name="noc-sim-r7", diff --git a/docs/design/performance/providers.zh.md b/docs/design/performance/providers.zh.md index e023b54..1096027 100644 --- a/docs/design/performance/providers.zh.md +++ b/docs/design/performance/providers.zh.md @@ -75,7 +75,7 @@ from blueprinting.analysis import ( SimulatorPerformanceImporter, TabularImportSpec, ) -from blueprinting.synthesizer.frozen import FrozenDict +from blueprinting.schema.frozen import FrozenDict spec = TabularImportSpec( name="noc-sim-r7", diff --git a/docs/exploration/index.en.md b/docs/exploration/index.en.md index 415b3f9..101d960 100644 --- a/docs/exploration/index.en.md +++ b/docs/exploration/index.en.md @@ -101,4 +101,4 @@ Today the repository has a strong workload-accounting and formal-analysis founda It does not yet expose a first-class `ArchitectureBlueprint`, broad hardware design-space search, a connected discrete-event simulator, energy/area/cost models, or Pareto exploration. These are the next product-defining slices and are tracked in [implementation status](../project/status.md) and the [roadmap](../project/roadmap.md). -Continue with the [hardware design space](design-space.md), then follow the [exploration workflow](workflow.md). +Continue with the [hardware design space](design-space.md), then follow the [exploration workflow](workflow.md). The interactive entry point is the [exploration workspace](workspace.md). diff --git a/docs/exploration/index.zh.md b/docs/exploration/index.zh.md index 610cad0..3de0be7 100644 --- a/docs/exploration/index.zh.md +++ b/docs/exploration/index.zh.md @@ -101,4 +101,4 @@ workload semantics 当前还没有 first-class `ArchitectureBlueprint`、广泛 hardware design-space search、贯通的 discrete-event simulator、energy/area/cost model 或 Pareto exploration。这些是下一批定义产品的纵向切片，记录在[实现状态](../project/status.md)与[路线图](../project/roadmap.md)中。 -接下来阅读[硬件设计空间](design-space.md)，然后沿[探索工作流](workflow.md)继续。 +接下来阅读[硬件设计空间](design-space.md)，然后沿[探索工作流](workflow.md)继续。交互式探索入口见[探索工作空间](workspace.md)。 diff --git a/docs/exploration/workspace.en.md b/docs/exploration/workspace.en.md new file mode 100644 index 0000000..b912e3a --- /dev/null +++ b/docs/exploration/workspace.en.md @@ -0,0 +1,49 @@ +# Exploration Workspace + +The exploration workspace is the interactive surface of the Blueprinting workbench: a single-page NiceGUI application backed by the framework-neutral `BlueprintingService`. It is a presentation layer over the analysis stack — it introduces no new semantic layer and never becomes an alternative source of workload truth. + +!!! note "Terminology" + “Workspace” appears in two distinct senses in the documentation: this page describes the workbench's **exploration workspace** (the interactive views for four modes); `PortablePlanIR` separately defines the `WORKSPACE` buffer role, a capacity constraint for abstract working memory, in [Planning and Execution IR](../design/ir/planning-execution.md). + +## What the workspace is + +The workspace renders one of four mode views, all sharing the same configuration surface. Analysis runs outside the UI event loop; a result is shared across views and marked stale after configuration changes; failed candidates remain visible as structured diagnostics instead of vanishing silently. It consumes the framework-neutral services in `application/` and shares the same typed contracts as the CLI. + +## Shared configuration surface + +Point and batch modes share one configuration dialog: model/execution presets (from the retained JSON presets in `data/`), TP/PP/DP topology, calibration mode (system-evidence curve vs theoretical peak baseline), and candidate bounds. Quick controls and the full configuration stay in sync. + +## Workspace modes + +### Point lens + +Focuses on one case: runs the `ModelIR -> DistributedTaskIR -> PortablePlanIR` derivation, resolves evidence estimates, and shows task-level contributions, resource constraints, and evidence boundaries. A failed derivation keeps a diagnostic with lineage instead of fabricating a performance number. + +### Batch lens + +Treats a set of TP/PP/DP cases as a whole: each case derives independently, exposing distributions, upper/lower bounds, and the feasible boundary while shrinking the candidate space. Failed items retain status and diagnostics and participate in the distribution statistics. + +### Evidence lab + +A read-only evidence catalog: pinned Vidur Phi-2/A100 records with exact selectors. GEMM primitives compare measured versus analytical roofline on identical workload facts; the measured series shows exact sample points without claiming interpolation; attention and other operations appear in the coverage catalog only. + +### Numeric lens + +Hosts the [Floating-Point Numerical Analysis](../design/numerical-analysis.md) panel: formats, encoding, dynamic range, and operation boundaries. It is usable independently of workload analysis and does not require running a derivation first. + +## Workspace invariants + +- no eager analysis on load; +- analysis executes outside the UI event loop (`io_bound`), keeping the interface responsive; +- a single result is shared across views and marked stale after configuration changes; +- sweep candidates retain per-case status and failure diagnostics; +- evidence is read-only: the lab never writes back to evidence or canonical IR; +- the optional portable dependency Chrome Trace export is explicitly marked `executable=false` and is not a `TimelineBundle`. + +## Architecture relationship + +The workbench consumes `application/` services and presents canonical derivation audits, cost resolution, and evidence catalogs. It does not construct canonical plans itself; every analysis entry point shares the typed contracts and session bindings of the CLI. + +## Current boundary + +The workspace is an analysis and audit surface, not a simulator. It has no first-class `ArchitectureBlueprint` editing, no design-space search, and no discrete-event simulation; those remain planned product slices (see [Implementation Status](../project/status.md) and the [exploration workflow](workflow.md)). diff --git a/docs/exploration/workspace.zh.md b/docs/exploration/workspace.zh.md new file mode 100644 index 0000000..b792d0c --- /dev/null +++ b/docs/exploration/workspace.zh.md @@ -0,0 +1,49 @@ +# 探索工作空间 + +探索工作空间是 Blueprinting workbench 的交互面：一个由 framework-neutral `BlueprintingService` 支撑的单页 NiceGUI 应用。它是分析栈上的 presentation layer——不引入新的 semantic layer，也绝不成为第二份 workload truth。 + +!!! note "术语澄清" + “工作空间”在文档中有两个含义，不要混淆：本页描述的是 workbench 的**探索工作空间**（四种模式的交互视图）；`PortablePlanIR` 中另有 `WORKSPACE` buffer role，表达抽象工作内存的容量约束，见[规划与执行 IR](../design/ir/planning-execution.md)。 + +## 工作空间是什么 + +工作空间按模式渲染四种视图，全部共享同一配置面。Analysis 在 UI event loop 之外执行；结果跨视图共享，配置变更后标记 stale；失败的 candidate 保留为结构化 diagnostic 而不是静默消失。它消费 `application/` 的 framework-neutral service，与 CLI 走同一套 typed contract。 + +## 共享配置面 + +单点与批量模式共享同一配置对话框：model/execution preset（来自 `data/` 的保留 JSON preset）、TP/PP/DP 拓扑、calibration mode（系统证据曲线 vs 理论峰值基线）与 candidate 范围。快速控件与完整配置双向同步。 + +## 工作空间模式 + +### 单点剖析（POINT LENS） + +聚焦一个 case：执行 `ModelIR -> DistributedTaskIR -> PortablePlanIR` 推导，解析 evidence estimate，展示任务级贡献、资源约束与证据边界。推导失败时保留带 lineage 的 diagnostic，而不是给出虚构的 performance number。 + +### 批量探索（BATCH LENS） + +把一组 TP/PP/DP case 作为整体：每个 case 独立推导，观察分布、上下界与可行边界，逐步收缩候选空间。失败项保留状态与诊断，并参与分布统计。 + +### 性能证据（EVIDENCE） + +只读 evidence catalog：固定的 Vidur Phi-2/A100 exact-selector 记录。GEMM primitive 以相同 workload facts 对比 measured 与 analytical roofline；measured series 只显示精确 sample point，不声明插值；attention 与其他 operation 只进入 coverage catalog。 + +### 浮点分析（NUMERIC） + +承载[浮点数数值分析](../design/numerical-analysis.md)面板：格式、编码、动态范围与运算边界。它独立于 workload analysis 可用，不要求先运行推导。 + +## 工作空间不变量 + +- 载入时不执行 eager analysis； +- analysis 在 UI event loop 外执行（`io_bound`），界面保持响应； +- 单个结果跨视图共享，配置变更后标记 stale； +- sweep candidate 保留 per-case 状态与失败诊断； +- evidence 只读：lab 从不回写 evidence 或 canonical IR； +- 可选的 portable dependency Chrome Trace 导出明确标记 `executable=false`，不是 `TimelineBundle`。 + +## 架构关系 + +Workbench 消费 `application/` service 并展示 canonical derivation audit、cost resolution 与 evidence catalog。它本身不构造 canonical plan；所有分析入口与 CLI 共享同一 typed contract 与 session binding。 + +## 当前边界 + +工作空间是分析/审计面，不是 simulator。它没有 first-class `ArchitectureBlueprint` 编辑、design-space search 或 discrete-event simulation；这些仍是 planned product slice（见[实现状态](../project/status.md)与[探索工作流](workflow.md)）。 diff --git a/mkdocs.yml b/mkdocs.yml index 4d67f63..5b8af1b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,7 @@ nav: - Why Blueprinting: exploration/index.md - Hardware Design Space: exploration/design-space.md - Exploration Workflow: exploration/workflow.md + - Exploration Workspace: exploration/workspace.md - Models and Simulation: - Hardware Architecture Model: modeling/hardware.md - Workload and Mapping Model: modeling/workload.md @@ -66,6 +67,7 @@ nav: - Timeline Staging Path: design/timeline-path.md - Golden Derivation Walkthrough: design/walkthrough.md - Analysis Module Architecture: design/modules.md + - Floating-Point Numerical Analysis: design/numerical-analysis.md - Formal Representations: - Representation Stack: design/ir/index.md - Workload and Distribution Models: design/ir/model-distributed.md @@ -109,6 +111,7 @@ plugins: Why Blueprinting: 为什么叫 Blueprinting Hardware Design Space: 硬件设计空间 Exploration Workflow: 探索工作流 + Exploration Workspace: 探索工作空间 Models and Simulation: 模型与仿真 Hardware Architecture Model: 硬件架构模型 Workload and Mapping Model: 工作负载与映射模型 @@ -126,6 +129,7 @@ plugins: Timeline Staging Path: Timeline 阶段路径 Golden Derivation Walkthrough: 完整推导示例 Analysis Module Architecture: 分析模块架构 + Floating-Point Numerical Analysis: 浮点数数值分析 Formal Representations: 形式化表示 Representation Stack: 表示体系 Workload and Distribution Models: 工作负载与分布模型