Skip to content

Add SegmentedNumber, CyclicCounter, and numeric footprint docs - #13

Merged
NikolayChirkov merged 9 commits into
mainfrom
feature/segmented-number
Sep 2, 2026
Merged

NikolayChirkov merged 9 commits into
mainfrom
feature/segmented-number

Conversation

@NikolayChirkov

@NikolayChirkov NikolayChirkov commented Aug 29, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Add header-only SegmentedNumber (ae::seg::Format / Compile) for piecewise-quantized physical values with Formula encode/decode over FixedPoint (Rep width <= 32), no per-code lookup tables.
  • Add CyclicCounter<Wire,Value>: full local counter, truncated wire bits, contextual restore/advance only (stateless deserialize does not compile).
  • Document ESP32-C6 footprints, constant tables, object/stack sizes, and desktop benchmarks; add tools/measure_esp32c6_footprint.py and tools/generate_footprint_docs.py.

Test plan

  • GCC Debug + Release (ctest, warnings as errors)
  • Clang Debug + Release
  • MSVC Debug + Release
  • ESP32-C6 object footprint -Os / -O2 (see docs/footprint.md)
  • Desktop numeric-bench (see docs/benchmarks.md)
  • CI matrix on this PR

NikolayChirkov and others added 4 commits August 28, 2026 17:24
…al values.

Keep existing TieredInt/FixedPoint/Exponential wire formats unchanged and compile the packed rank from an independent curve layout.

Co-authored-by: Cursor <cursoragent@cursor.com>
Introduce CyclicCounter for truncated modular wire counters with
nearest unambiguous full-value restore and TryAdvance.

Co-authored-by: Cursor <cursoragent@cursor.com>
Drop wire_traits for CyclicCounter so truncated wire values cannot
be mistaken for a full counter without a live restore base.

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@NikolayChirkov NikolayChirkov changed the title Add header-only SegmentedNumber piecewise quantized type Add SegmentedNumber, CyclicCounter, and numeric footprint docs Aug 30, 2026
@NikolayChirkov

Copy link
Copy Markdown
Collaborator Author

Reviewer request: Anton Kitaev. GitHub profile realkoldun (display name Anton Kitaev) is not a collaborator on this repo, so the formal review request is assigned to @BartolomeyKant. Please reassign if Anton should review under a different login.

@BartolomeyKant BartolomeyKant left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While those types are not trivial to understand it should be properly documented.
Start each file with short description:

  • motivation
  • known analogous if any?
  • brief description how to use
  • brief description how it works

Comment thread .github/workflows/ci-cd-tests.yml Outdated
Comment thread ae-numeric/cyclic_counter.h
@NikolayChirkov
NikolayChirkov force-pushed the feature/segmented-number branch from a319a87 to 7db38b0 Compare August 31, 2026 05:11

Copy link
Copy Markdown
Collaborator Author

Addressed the documentation request in 7db38b0aeb465c9de9def37e9bcf8608ddc70afb.

Added file-level architecture overviews to the public and internal numeric headers. Each overview now covers the motivation, related/analogous concepts, brief usage, how the implementation works, and the important invariants or public/internal boundary.

The documentation covers CyclicCounter, the SegmentedNumber public API and wire/floating adapters, the schema/curve/compiler/formula layers, and the shared FixedPoint/integer math layers. This commit changes comments only: no API, wire ABI, algorithms, schema hashes, numeric constants, or generated data changed.

The documentation commit is a single clean commit on top of the CI cleanup. git diff --check passed; the full PR CI matrix has been triggered for the new head.

Comment thread ae-numeric/segmented_number.h Outdated
Comment thread ae-numeric/segmented_number.h Outdated
Comment thread ae-numeric/cyclic_counter.h
Comment thread ae-numeric/details/segmented_compiler.h Outdated
Comment thread ae-numeric/details/segmented_math.h Outdated
Generalize rank/wire conversion, add SegmentedFormatSpec and CyclicCounter arithmetic, unify segmented internals under ae::seg::detail, and document the intentional 32-bit Formula backend boundary with tests and cpplint fixes.

Co-authored-by: Cursor <cursoragent@cursor.com>
@NikolayChirkov

Copy link
Copy Markdown
Collaborator Author

Addressed the five review threads in 7ce31f7:

  • generalized integral/TieredInt rank conversion;
  • added SegmentedFormatSpec;
  • added explicit integral-like CyclicCounter arithmetic;
  • unified segmented internals under ae::seg::detail;
  • documented and enforced the intentional 32-bit Formula backend boundary.

All local compiler configurations (GCC/Clang/MSVC Debug+Release), compile-fail tests, cpplint, and golden wire tests pass. GitHub Actions: in progress (run 33556521462).

Co-authored-by: Cursor <cursoragent@cursor.com>
@NikolayChirkov
NikolayChirkov merged commit 53f1adf into main Sep 2, 2026
7 checks passed
@NikolayChirkov
NikolayChirkov deleted the feature/segmented-number branch September 2, 2026 09:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants