1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
# Contributing to the SAME Analog Modular Ecosystem Specification
Thank you for your interest in contributing to the **SAME Analog Modular
Ecosystem**.
Because SAME is a metrology-grade computing specification targeting
$10\text{ ppm}$ precision and $90\text{ dB}$ SNR, we maintain strict
engineering, mathematical, and procedural standards for all contributions. This
guide outlines how to set up your environment, write compliant Typst markup,
enforce our executable math paradigm, and submit pull requests.
## 1. The Executable Specification Paradigm
The defining principle of this repository is that **the specification is its own
test suite**.
We do not manually transcribe calculated values into prose. Every mathematical
claim, noise derivation, tolerance budget, and physical scaling law presented in
the text must be directly accompanied by a compile-time assertion using our
custom metrology library (`lib/assert-aeq.typ` and `lib/apply-prefix.typ`).
### The Rule of Zero-Copy Math
When adding or modifying any numerical derivation:
1. **Calculate programmatically:** Define variables using Typst math expressions
and SI helpers.
2. **Assert sanity at compile time:** Pass the calculated variable and the
expected target through `#assert-aeq`.
3. **Typeset the output:** Render the expression using standard Typst math
markup.
#### Example
```typst
#let v_noise_excess = (
5 * calc.pow(10, -15 / 20) * calc.sqrt(20000) * calc.pow(10, -6)
)
// 1. Compile-time assertion using named SI prefixes
#assert-aeq(v_noise_excess, apply-prefix(125.74, "micro"))
// 2. Visual presentation block
$
V_("noise","excess") & approx qty(5, "V") times 10^(-15/20) times sqrt(20000) dot 10^-6 \
V_("noise","excess") & approx qty(5, "V") times 0.1778 times num("141.4e-6") approx qty(125.74, "uV")
$
``````
If you modify a foundational parameter (e.g. system bandwidth or reference
voltages), Typst must re-evaluate all downstream derivations. **If any assertion
fails, the PDF build will halt.**
## 2. Development Setup
### Prerequisites
- **Typst CLI**: Version `0.15.1` or higher.
- **Git:** For version control.
### Building and Testing
1. **Clone the repository:**
```bash
git clone git@denischevalier.fr:/srv/git/same.git
cd same
```
2. **Enable git hooks:** To automatically inject required SPDX license headers
on newly created `.typ` files:
```bash
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks
```
3. **Run a live watch build:**
```bash
typst watch preamble.typ specification.pdf
```
*If your edits break an assertion metrology check anywhere in the 90+ pages,
Typst will throw an immediate compiler error in your terminal.*
4. **Perform a clean release compile:**
```bash
typst compile preamble.typ specification.pdf
```
## 3. Structural & Content Guidelines
### Enumerating Physical Error Sources (Section 4.3)
When adding a new error mechanism or circuit non-ideality to Section 4.3, you
**must** follow the standard 6-part structure:
1. **Physical mechanism:** What physical/thermodynamic law causes this error?
2. **Mathematical model:** First-principles equations governing the behavior.
3. **Typical magnitude:** Numerical evaluation using commodity through-hole
component specs.
4. **Where it enters:** Circuit nodes, PCB traces, or mechanical interfaces
vulnerable to this mechanism.
5. **Scaling law:** How the error scales with frequency, temperature, resistance,
bandwidth, or geometry.
6. **Compensation strategy:** Cross-reference to the topological mitigation or
physical layout rules.
### Vector Graphics & Visual Standards
- **No Binary Raster Graphics:** Do not commit `.png`, `.jpg`, or bitmap
images for technical drawings, schematics, or plots.
- **CeTZ & CeTZ-Plot:** All mechanical dimensions, panel grids, and mathematical
curves must be written natively using `CeTZ` or `CeTZ-plot` inside `/diagrams`
or `/charts`.
- **Circuits with Zap:** Circuits schematics must be written using `zap` code
directly within the Typst source tree, under `/schematics`.
- **Typographic Consistency:** All text inside vector graphics must use the
document's native typography and unit formatting library (`lib/unify.typ`).
## 4. Licensing & SPDX Headers
This project is tri-licensed to properly cover prose, hardware CAD, and
executable code. **Every new file commited to the repository must include the
appropriate SPDX header at line 1:
```typst
// / SPDX-FileCopyrightText: 2026 Denis Chevalier \<perso\@denischevalier.fr>
// / SPDX-License-Identifier: CC-BY-SA-4.0
// / SPDX-License-Identifier: CERN-OHL-S-2.0+
// / SPDX-License-Identifier: GPL-3.0-or-later
//
// The prose, explanatory text, rendered figures, tables, and mathematical
// content of this specification are licensed under CC BY-SA 4.0. If a later
// version of CC BY-SA is published, the author grants permission to distribute
// this work under that later version as well.
//
// Hardware designs contained herein (schematics, PCB layouts, mechanical
// drawings, and CAD models) are licensed under CERN-OHL-S-2.0+.
//
// All executable code, helper libraries (`lib/*`), metrology assertions, and
// embedded verification scripts throughout the source documents are licensed
// under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
```
## 5. Submitting Pull Requests
To keep the history clean and maintainable:
1. **Atomic Commits:** Make small, focused commits. Separate structural Typst
refactoring from mathematical derivations and text revisions.
2. **Verify Local Builds:** Ensure `typst compile preamble.typ` completes with
zero errors and zero warnings before opening a PR.
3. **PR Description Checklist:**
- Explain the engineering rationale behind any parameter changes.
- Cite relevant metrology literature, datasheets, or academic papers if
introducing new concepts.
- Confirm all assertions pass.
4. **Clean Diffs:** Avoid re-formating unrelated `.typ` files. Keep line breaks
logical (semantic line breaks are preferred).
## Questions or Discussion?
If you are planning a major structural change to the specification, please send
a mail to [Denis Chevalier](perso@denischevalier.fr) to discuss the
architectural implications before writing code.
|
