docs(book): Add the eunomia datatype-law book (outline) - #51
Conversation
|
Caution The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased. |
📝 WalkthroughWalkthroughAdded a complete mdBook for eunomia’s datatype documentation. The change defines the book structure, documents scalar and numeric abstractions, adds planned examples, configures HTML output, and deploys the generated book through GitHub Pages. ChangesEunomia mdBook
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/book/book.toml`:
- Around line 16-18: Update the [output.html] configuration in book.toml to set
no-section-label = true, preserving the manually numbered chapter titles in
docs/book/SUMMARY.md without duplicate automatic labels.
In `@docs/book/byte_layout.md`:
- Around line 5-13: Update the “Zeroable” and “Pod” section in
docs/book/byte_layout.md to separate their safety contracts: require only Pod
when viewing an existing value as bytes via bytes_of, require Zeroable for
all-zero construction via Zeroable::zeroed, and state that APIs performing both
operations require both traits.
In `@docs/book/examples/choosing_precision.md`:
- Around line 8-17: Update the precision comparison in the documented example to
call the metric reference error rather than round-trip error, and define the
reproducible workload by naming the input series, term count, summation order,
and f64 reference calculation. Ensure the table values are explicitly presented
as measurements for that workload, or relabel the table as illustrative
precision limits instead of fixed measured results.
In `@docs/book/examples/complex_arithmetic.md`:
- Around line 17-24: Update the byte round-trip outline in complex_arithmetic.md
to state that external GPU/FFI buffers must have a length aligned to a Complex64
element multiple and a suitably aligned pointer, or use an unaligned
single-element read. Also add this alignment precondition and its handling to
the DoR example.
In `@docs/book/examples/rounding_behaviour.md`:
- Around line 20-23: Update the rounding behaviour documentation to define
“small powers of two” as values representable as finite F16 numbers, and limit
exact round-trip assertions to that range. Add separate examples for underflow
and overflow that assert their expected rounded results rather than exact
round-trips.
- Around line 24-25: Update the rounding-behaviour outline to use a consistent
error metric: compare absolute error with 0.5 * ulp(reference) for normal
values, and explicitly define separate handling for zero and subnormal values;
alternatively, specify a mathematically derived relative bound instead of the
half-ulp comparison.
In `@docs/book/integer_types.md`:
- Around line 30-33: Update the “Source construction” guidance to remove the
invalid `v as Self` pattern for I8, I16, and I32 wrappers. Describe constructing
each tuple wrapper from a cast inner primitive, or using the existing
CastFrom<i32> conversion, while preserving the guidance about explicit
precision-correct construction.
In `@docs/book/packed_formats.md`:
- Around line 5-24: Update the opening documentation in the packed module
description to limit the packing and 2× memory-reduction claims to the 4-bit
formats F4 and Bf4. Describe F8 and Bf8 as already occupying one full u8 and
distinguish their format conversion or unpacking support from 4-bit packing;
keep the listed APIs and archival details unchanged.
In `@docs/book/README.md`:
- Around line 16-33: Update the “What it does not own” section to remove the
contradiction with the documented conversion kernel, COW buffers, and
SIMD-accelerated unpack. Narrow the exclusions to general-purpose computation,
allocation, scheduling, backend, and execution concerns, while explicitly
preserving the datatype-local storage and conversion exceptions already listed
above.
- Around line 51-54: Update the documentation paragraph around the `examples/`
reference to describe them as “planned example outlines” rather than “worked
examples,” while preserving the surrounding explanation and outline-edition
status.
In `@docs/book/scalar_fields.md`:
- Around line 11-12: Update the complex-number description in scalar_fields.md
to distinguish representation from arithmetic: state that the pair (re, im) is
the storage representation, while only addition and scalar operations are
componentwise; describe multiplication and division as following complex-field
rules. Remove any wording that implies componentwise complex multiplication.
- Around line 39-41: Update the “Ordered real scalars” description in
scalar_fields.md to call the ordering provided by PartialOrd a “partial order”
instead of a “total order,” while leaving the rest of the documented RealField
behavior unchanged.
In `@docs/book/scalar_types.md`:
- Around line 44-49: Qualify the bytemuck trait claim in
docs/book/scalar_types.md lines 44-49 so it states that Pod/Zeroable
implementations are available only with the bytemuck feature, while keeping the
unconditional native guarantees distinct. Apply the same qualification to the
Complex<T> claim in docs/book/complex_numbers.md lines 34-36.
- Around line 5-12: Update the floating-point equation description in the scalar
types documentation to explicitly scope it to normal finite values, and avoid
claiming that (E, M, B) alone determines all representable values unless
subnormals, NaN, and infinity are also documented. Preserve the existing
definitions for sign, significand, and exponent within the normal finite case.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 00dc8d73-f8a1-4dad-b4ac-7581783292d4
📒 Files selected for processing (21)
.github/workflows/book-pages.ymldocs/book/README.mddocs/book/SUMMARY.mddocs/book/book.tomldocs/book/byte_layout.mddocs/book/cast_lattice.mddocs/book/complex_numbers.mddocs/book/conversion_kernel.mddocs/book/element_operations.mddocs/book/examples/choosing_precision.mddocs/book/examples/complex_arithmetic.mddocs/book/examples/rounding_behaviour.mddocs/book/float_element.mddocs/book/integer_types.mddocs/book/numeric_element.mddocs/book/packed_formats.mddocs/book/relative_equality.mddocs/book/scalar_fields.mddocs/book/scalar_types.mddocs/book/stack_position.mddocs/book/unit_scalar.md
| [output.html] | ||
| no-section-label = false | ||
| mathjax-support = true |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repository files relevant to mdBook:"
git ls-files | rg '(^|/)book\.toml$|(^|/)SUMMARY\.md$|docs/book/' | sed -n '1,120p'
echo
echo "docs/book/book.toml:"
if [ -f docs/book/book.toml ]; then
cat -n docs/book/book.toml
fi
echo
echo "docs/book/SUMMARY.md (first 180 lines):"
if [ -f docs/book/SUMMARY.md ]; then
sed -n '1,180p' docs/book/SUMMARY.md | cat -n
fi
echo
echo "Search no-section-label usages:"
rg -n 'no-section-label|mathjax-support|site-url' .Repository: ryancinsight/eunomia
Length of output: 3565
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Available mdbook version/tooling:"
command -v mdbook || true
mdbook --version 2>/dev/null || true
echo
echo "Check for local mdbook/docs tooling indicators:"
git ls-files | rg '(^|/)(cargo\.lock|package\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb|\.github/workflows/.*)' | sed -n '1,120p'Repository: ryancinsight/eunomia
Length of output: 309
🌐 Web query:
mdBook output.html no-section-label true disable section labels
💡 Result:
To disable numeric section labels in your mdBook output, you should add the following configuration to your book.toml file under the [output.html] table [1][2]: [output.html] no-section-label = true Setting no-section-label to true removes numeric labels (such as "1." or "2.1") from the table of contents [1][3]. By default, this option is false [1][2]. Note: Development in the mdBook repository includes plans to rename this configuration key to section-label-toc with a inverted default behavior (defaulting to true) to improve clarity [4]. However, as of the current standard documentation, no-section-label = true remains the correct directive to disable these labels [1][2][5].
Citations:
- 1: https://rust-lang.github.io/mdBook/format/configuration/renderers.html?highlight=book.toml
- 2: http://rust-lang.github.io/mdBook/format/configuration/renderers.html
- 3: https://wofwca.github.io/mdBook/format/config.html
- 4: Rename no-section-label to section-label-toc rust-lang/mdBook#3091
- 5: https://docs.rs/mdbook-renderer/latest/mdbook_renderer/config/struct.HtmlConfig.html
Disable automatic section labels or remove the manual numbers.
docs/book/SUMMARY.md uses numbered chapter titles like 1. Floating-Point ScalarTypes, and no-section-label = false enables mdBook’s numeric section labels in the table of contents. This creates duplicate numbering. Set no-section-label = true if the manual numbers are intentional.
Proposed fix
. ```diff -no-section-label = false +no-section-label = true ```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [output.html] | |
| no-section-label = false | |
| mathjax-support = true | |
| [output.html] | |
| no-section-label = true | |
| mathjax-support = true |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/book.toml` around lines 16 - 18, Update the [output.html]
configuration in book.toml to set no-section-label = true, preserving the
manually numbered chapter titles in docs/book/SUMMARY.md without duplicate
automatic labels.
| Reinterpreting a value as raw bytes is safe only when the type's layout | ||
| permits it. Two facts must hold: | ||
|
|
||
| 1. **Zeroable** — the all-zero bit pattern is a valid, inhabited value | ||
| (this excludes types with a validity niche at zero, such as `NonZeroU32` | ||
| or `&T`). | ||
| 2. **Pod** (plain-old-data) — every bit pattern of `size_of::<Self>()` | ||
| bytes is a valid `Self`, and the type carries no padding or invalid | ||
| representations. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Separate the Pod and Zeroable safety contracts.
bytes_of accepts only T: Pod in crates/eunomia/src/layout/bytes.rs:36-40; Zeroable is not required to view an existing value as bytes. Zeroable is required for all-zero construction through Zeroable::zeroed. State these as separate requirements, and require both only for APIs that perform both operations.
Proposed wording
-Reinterpreting a value as raw bytes is safe only when the type's layout
-permits it. Two facts must hold:
+Viewing an existing value as raw bytes requires a `Pod` layout.
+Creating a value from all-zero bytes requires `Zeroable`. APIs that perform
+both operations require both contracts.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/byte_layout.md` around lines 5 - 13, Update the “Zeroable” and
“Pod” section in docs/book/byte_layout.md to separate their safety contracts:
require only Pod when viewing an existing value as bytes via bytes_of, require
Zeroable for all-zero construction via Zeroable::zeroed, and state that APIs
performing both operations require both traits.
| The precision trade-off across the eunomia scalar vocabulary: computing the | ||
| same accumulated sum in `F32`, `F64`, `F16`, and `Bf16`, and reporting the | ||
| round-trip error against the `f64` reference. | ||
|
|
||
| | Scalar | Storage | Relative error vs `f64` | | ||
| |---|---|---| | ||
| | `F64` | `u64` | reference | | ||
| | `F32` | `u32` | ~1e-7 (single precision) | | ||
| | `F16` (binary16) | `u16` | ~1e-3 (half precision) | | ||
| | `Bf16` (E8M7) | `u16` | ~4e-3 (bfloat range) | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Define the measured error before publishing fixed values.
Lines 8-10 describe an accumulated-sum comparison but call the result “round-trip error”. Lines 12-17 provide fixed values without a named series, term count, summation order, or a distinction between measured workload error and format precision. Rename the metric to reference error and define the workload, or label the table as illustrative precision limits. Otherwise the planned example cannot reproduce the table.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/examples/choosing_precision.md` around lines 8 - 17, Update the
precision comparison in the documented example to call the metric reference
error rather than round-trip error, and define the reproducible workload by
naming the input series, term count, summation order, and f64 reference
calculation. Ensure the table values are explicitly presented as measurements
for that workload, or relabel the table as illustrative precision limits instead
of fixed measured results.
| - `bytemuck::cast_slice` round-trip through raw bytes (chapter 10) | ||
|
|
||
| ## Outline | ||
|
|
||
| - Build a complex phasor `re + im·i` from real measurements | ||
| - Apply a complex product and quotient, checking results with | ||
| `assert_relative_eq!` | ||
| - Cast a slice of `Complex64` to bytes and back via the `Pod` contract |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 5 \
'cast_slice|try_cast_slice|pod_read_unaligned|unaligned|Complex64|Pod|Zeroable' \
crates/eunomia docs/adr docs/bookRepository: ryancinsight/eunomia
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== book_complex_arithmetic.rs =="
if [ -f crates/eunomia/examples/book_complex_arithmetic.rs ]; then
cat -n crates/eunomia/examples/book_complex_arithmetic.rs
else
echo "crate example file not found"
fi
echo
echo "== relevant layout definitions =="
sed -n '1,220p' crates/eunomia/src/types/complex/mod.rs | cat -n
sed -n '40,110p' crates/eunomia/src/types/mod.rs | cat -n
echo
echo "== complex numeric assertions/search =="
rg -n -C 3 'size_of::<Complex64>|align_of::<Complex64>|Complex<f64>|Complex64>::(ZERO|ONE)|pod_read_unaligned|try_cast_slice|cast_slice' crates/eunomia/src crates/eunomia/examples || trueRepository: ryancinsight/eunomia
Length of output: 20957
State the alignment precondition for the byte round-trip.
cast_slice checks element length and pointer alignment, so external GPU/FFI byte buffers need an aligned Complex64-multiple length or an unaligned single-element read. Add this precondition to the outline and cover it in the DoR example.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/examples/complex_arithmetic.md` around lines 17 - 24, Update the
byte round-trip outline in complex_arithmetic.md to state that external GPU/FFI
buffers must have a length aligned to a Complex64 element multiple and a
suitably aligned pointer, or use an unaligned single-element read. Also add this
alignment precondition and its handling to the DoR example.
| - Convert `1.0f32` and small powers of two, asserting exact | ||
| round-trips (`0x3C00` for `F16`) | ||
| - Feed exact ties (values exactly midway between two representable | ||
| values) and show the even-significand choice |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Limit exact-round-trip assertions to representable values.
“Small powers of two” is underspecified. Values outside the finite F16 range do not round-trip exactly. State the range covered by the exact assertions, and test underflow and overflow as separate expected-rounding cases.
Suggested wording
- Convert `1.0f32` and small powers of two, asserting exact
- round-trips (`0x3C00` for `F16`)
+ Convert `1.0f32` and powers of two in the documented representable
+ range, asserting exact round-trips (`0x3C00` for `F16`)
+ and testing underflow and overflow separately.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Convert `1.0f32` and small powers of two, asserting exact | |
| round-trips (`0x3C00` for `F16`) | |
| - Feed exact ties (values exactly midway between two representable | |
| values) and show the even-significand choice | |
| - Convert `1.0f32` and powers of two in the documented representable | |
| range, asserting exact round-trips (`0x3C00` for `F16`) | |
| and testing underflow and overflow separately. | |
| - Feed exact ties (values exactly midway between two representable | |
| values) and show the even-significand choice |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/examples/rounding_behaviour.md` around lines 20 - 23, Update the
rounding behaviour documentation to define “small powers of two” as values
representable as finite F16 numbers, and limit exact round-trip assertions to
that range. Add separate examples for underflow and overflow that assert their
expected rounded results rather than exact round-trips.
| Each chapter maps the theory onto the crate's public API, and worked examples | ||
| in `examples/` show the abstractions in use. This is the outline edition: the | ||
| chapter structure is complete, and the chapters themselves land as DoR items | ||
| per subsystem. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Describe the example files according to their current status.
This paragraph calls the files in examples/ worked examples, but the PR adds outline chapters. Replace “worked examples” with “planned example outlines” until those chapters contain worked code or results.
Proposed wording
- in `examples/` show the abstractions in use.
+ in `examples/` outline the planned abstractions and use cases.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Each chapter maps the theory onto the crate's public API, and worked examples | |
| in `examples/` show the abstractions in use. This is the outline edition: the | |
| chapter structure is complete, and the chapters themselves land as DoR items | |
| per subsystem. | |
| Each chapter maps the theory onto the crate's public API, and planned example outlines | |
| in `examples/` outline the planned abstractions and use cases. This is the outline edition: the | |
| chapter structure is complete, and the chapters themselves land as DoR items | |
| per subsystem. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/README.md` around lines 51 - 54, Update the documentation paragraph
around the `examples/` reference to describe them as “planned example outlines”
rather than “worked examples,” while preserving the surrounding explanation and
outline-edition status.
| For complex numbers the same operations exist, but the order does not — the | ||
| field is the pair `(re, im)` with componentwise arithmetic. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Do not describe complex multiplication as componentwise.
Complex<T> uses a component pair for representation, but only addition and scalar operations are componentwise. Multiplication and division follow complex-field rules. Update this sentence to avoid implying (a + bi)(c + di) = ac + bdi.
Proposed wording
- field is the pair `(re, im)` with componentwise arithmetic.
+ field is represented by the pair `(re, im)`; addition is componentwise, while multiplication and division follow complex-field rules.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| For complex numbers the same operations exist, but the order does not — the | |
| field is the pair `(re, im)` with componentwise arithmetic. | |
| For complex numbers the same operations exist, but the order does not — the | |
| field is represented by the pair `(re, im)`; addition is componentwise, while multiplication and division follow complex-field rules. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/scalar_fields.md` around lines 11 - 12, Update the complex-number
description in scalar_fields.md to distinguish representation from arithmetic:
state that the pair (re, im) is the storage representation, while only addition
and scalar operations are componentwise; describe multiplication and division as
following complex-field rules. Remove any wording that implies componentwise
complex multiplication.
| - **Ordered real scalars.** `RealField` adds the total order (`PartialOrd`), | ||
| the mathematical constants, and sign helpers to the `FloatElement` math | ||
| surface. Implemented for `f32`/`f64` (and the reduced float wrappers). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n -C 6 'trait RealField|PartialOrd|fn nan|impl.*RealField' \
docs/book/scalar_fields.md crates/eunomiaRepository: ryancinsight/eunomia
Length of output: 22158
🌐 Web query:
Rust std::cmp::PartialOrd NaN not ordered documentation total_cmp
💡 Result:
In Rust, floating-point types (f32 and f64) only implement the PartialOrd trait rather than the Ord trait because floating-point numbers do not satisfy the requirements of a total order [1][2]. Specifically, the IEEE 754 standard specifies that NaN (Not-a-Number) values are not equal to themselves and are not comparable to other numbers, which violates the reflexivity required for a total order [3][4]. Because PartialOrd is used, standard comparison operators like <, >, <=, and >= behave according to a strict or non-strict partial order where comparisons involving NaN return false or None [3][5]. For example, f64::NAN <= f64::NAN is false [3]. To enable sorting and other operations that require a total order, Rust provides the total_cmp method on both f32 and f64 [4][6]. This method implements the totalOrder predicate defined in IEEE 754-2008, providing a consistent ordering for all floating-point values, including NaNs, negative zeros, and positive zeros [4][7]. The ordering defined by total_cmp is [4][6][8]: 1. Negative quiet NaN 2. Negative signaling NaN 3. Negative infinity 4. Negative numbers 5. Negative subnormal numbers 6. Negative zero 7. Positive zero 8. Positive subnormal numbers 9. Positive numbers 10. Positive infinity 11. Positive signaling NaN 12. Positive quiet NaN Note that the ordering provided by total_cmp does not always align with the standard PartialOrd and PartialEq implementations (e.g., total_cmp distinguishes between negative and positive zero) [4][6].
Citations:
- 1: https://stackoverflow.com/questions/26489701/why-does-rust-not-implement-total-ordering-via-the-ord-trait-for-f64-and-f32
- 2: https://lib.rs/blog/tips/tip-14/
- 3: https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html
- 4: https://dev-doc.rust-lang.org/beta/std/primitive.f32.html
- 5: https://doc.rust-lang.org/1.93.0/std/cmp/trait.PartialOrd.html
- 6: https://doc.rust-lang.org/1.90.0/core/primitive.f32.html
- 7: https://rust.docs.kernel.org/core/primitive.f32.html
- 8: https://doc.rust-lang.org/1.60.0/core/primitive.f32.html
Use PartialOrd terminology accurately.
PartialOrd is a partial-order trait. f32 and f64 NaN values are unordered, while Rust’s total ordering for floats is exposed via total_cmp. Replace “total order” with “partial order”.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/scalar_fields.md` around lines 39 - 41, Update the “Ordered real
scalars” description in scalar_fields.md to call the ordering provided by
PartialOrd a “partial order” instead of a “total order,” while leaving the rest
of the documented RealField behavior unchanged.
| A floating-point number is a finite approximation to a real value, stored as | ||
|
|
||
| $$x = (-1)^{s} \cdot m \cdot 2^{e}$$ | ||
|
|
||
| with a sign bit `s`, a significand `m` of width `M` bits (plus the implicit | ||
| leading bit in normal numbers), and an exponent `e` biased by a format- | ||
| specific constant `B` over `E` bits. The set of representable values is | ||
| determined entirely by the triple `(E, M, B)`: |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Scope the floating-point equation to normal finite values.
The equation does not represent subnormals, NaN, or infinity. NumericElement exposes NAN and INFINITY in crates/eunomia/src/traits/numeric.rs:18-172. Label this equation as the normal finite case, or document the missing representations before claiming that (E, M, B) fully determines the complete value set.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/scalar_types.md` around lines 5 - 12, Update the floating-point
equation description in the scalar types documentation to explicitly scope it to
normal finite values, and avoid claiming that (E, M, B) alone determines all
representable values unless subnormals, NaN, and infinity are also documented.
Preserve the existing definitions for sign, significand, and exponent within the
normal finite case.
| - **Float-semantic comparisons.** `PartialEq`/`PartialOrd` for `F16`/`Bf16` | ||
| compare through `f32`, not bitwise, so `1.0` and `0x3C00` compare equal. | ||
| - **Exact layout.** `const _` assertions pin each type's size and alignment, | ||
| and every type is `bytemuck::Pod`/`Zeroable` (§10). | ||
| - **Precision-correct construction.** `FloatElement::from_f64` (on `F16`/ | ||
| `Bf16`) rounds through the native kernel rather than a truncating `as` cast. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Apply the bytemuck feature gate consistently.
The native Pod/Zeroable guarantees are unconditional, but the bytemuck implementations are feature-gated in docs/book/byte_layout.md.
docs/book/scalar_types.md#L44-L49: qualify thebytemucktrait claim with the feature.docs/book/complex_numbers.md#L34-L36: apply the same qualification toComplex<T>.
📍 Affects 2 files
docs/book/scalar_types.md#L44-L49(this comment)docs/book/complex_numbers.md#L34-L36
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/book/scalar_types.md` around lines 44 - 49, Qualify the bytemuck trait
claim in docs/book/scalar_types.md lines 44-49 so it states that Pod/Zeroable
implementations are available only with the bytemuck feature, while keeping the
unconditional native guarantees distinct. Apply the same qualification to the
Complex<T> claim in docs/book/complex_numbers.md lines 34-36.
1 participant
Closes the outline increment of ATLAS-BOOK-001 for the eunomia package (provider-first book sequencing #1).
High-level PR Summary
This PR establishes the complete mdBook documentation structure for the
eunomiadatatype-law package. It adds a full outline covering the numeric scalar vocabulary (IEEE-754 formats, complex numbers, integer types), element and field traits for generic programming, conversion and casting semantics, byte layout contracts, packed sub-byte formats, and the crate's position in the Atlas stack. The book includes 14 outline chapters organized into six parts, three example outlines, and a GitHub Actions workflow that publishes the book to GitHub Pages using the Atlas sharedbook-pagesworkflow pattern.⏱️ Estimated Review Time: 30-90 minutes
💡 Review Order Suggestion
docs/book/README.mddocs/book/SUMMARY.mddocs/book/book.tomldocs/book/scalar_types.mddocs/book/integer_types.mddocs/book/complex_numbers.mddocs/book/numeric_element.mddocs/book/float_element.mddocs/book/scalar_fields.mddocs/book/unit_scalar.mddocs/book/cast_lattice.mddocs/book/conversion_kernel.mddocs/book/byte_layout.mddocs/book/packed_formats.mddocs/book/relative_equality.mddocs/book/element_operations.mddocs/book/stack_position.mddocs/book/examples/choosing_precision.mddocs/book/examples/complex_arithmetic.mddocs/book/examples/rounding_behaviour.md.github/workflows/book-pages.ymlSummary by CodeRabbit