DEV Community: Gian Michele Pasinelli

CalcDocs Gets Even Better: Interactive Tolerance Propagation in the Distribution Webview in VS Code

Gian Michele Pasinelli — Thu, 25 Jun 2026 12:15:36 +0000

CalcDocs introduces an updated distribution-based uncertainty propagation engine integrated directly into its VS Code webview. The goal is to support engineers working with formulas and derived quantities where input variability is not negligible, and where spreadsheet-based workflows become a bottleneck in reviewability, traceability, and iteration speed.

The focus of this update is not only interactivity, but coherence between model, code, and documentation.

Problem context

In embedded and low-level engineering, calculations are rarely purely deterministic. Typical workflows involve:

nominal values with tolerances
measured parameters with noise
datasheet-derived ranges
assumptions that evolve during design

Despite this, most workflows still rely on:

spreadsheets disconnected from source control
scripts detached from documentation
manual propagation of uncertainty

This creates friction in:

reviewability
reproducibility
change tracking
design validation over time

CalcDocs addresses this by embedding both formula definition and uncertainty propagation into a single text-based model inside the editor.

Model overview

CalcDocs represents a system as:

a set of scalar or derived variables
optional input distributions per variable
a deterministic formula graph
a propagation engine producing output distributions

Each input variable can optionally be associated with a distribution (e.g. uniform, normal, bounded empirical models depending on configuration).

The system evaluates the full graph and produces an output distribution rather than a single scalar value.

Propagation engine

The current implementation uses a Monte Carlo-based propagation model.

At a high level:

Input variables are sampled according to their assigned distributions
The formula graph is evaluated for each sample set
Output samples are aggregated into a distribution
Summary statistics and histogram representation are computed for visualization

This approach is chosen for its:

robustness against non-linear transformations
simplicity of extension to arbitrary formula graphs
predictable behavior across heterogeneous inputs

Trade-offs are explicitly accepted in favor of correctness over closed-form approximations.

Webview integration

The VS Code webview provides a live view of:

formula structure
dependency graph
input distribution configuration
output distribution histogram

Changes to inputs or formulas trigger recomputation of the propagation model.

Input distribution model

Each input variable may be defined as:

deterministic constant
bounded uncertainty (e.g. min/max range)
probabilistic distribution (configurable per variable)

The intent is to make uncertainty explicit rather than implicit, and to keep assumptions part of the same version-controlled artifact as the formula itself.

This enables:

review of assumptions in code review workflows
traceability of design decisions
consistent propagation across iterations

Output representation

Outputs are represented as full distributions rather than point estimates.

The webview exposes:

histogram view (configurable binning, default 16 bins)
statistical summary (mean, variance, percentiles depending on configuration)
sensitivity indication via input variation impact

Workflow integration

A typical workflow becomes:

Define formula in CalcDocs syntax
Assign input distributions where uncertainty matters
Inspect propagated output distribution
Iterate assumptions directly in the same model

Because the entire model is text-based, it integrates naturally with:

git versioning
code review processes
diff-based review of assumptions
documentation pipelines

Design rationale

The system is intentionally constrained to remain:

deterministic at the model level (same seed/config → same result)
fully declarative (no hidden runtime state in formulas)
editor-native (no external execution context required)

This is particularly relevant in embedded workflows where reproducibility and auditability are often more important than raw performance.

Performance considerations

Monte Carlo propagation introduces computational cost proportional to:

O(N × G)

Where:

N = number of samples
G = number of nodes in the formula graph

To keep the UI responsive, recomputation is designed to be incremental where possible, with caching of intermediate evaluations when only parts of the graph change.

Use in embedded contexts

CalcDocs is particularly suited to:

tolerance stack-up analysis
sensor calibration models
analog front-end estimation
derived firmware constants validation
hardware/software expectation alignment

The key value is keeping the same calculation model shared between hardware design assumptions and firmware-level usage.

Iterative updates

The system is designed for frequent iteration of both formulas and assumptions. Any change in input distributions or structure triggers a recomputation of the propagation model, ensuring that documentation remains synchronized with the current state of the design.

Documentation and model specification

CalcDocs separates the engineering workflow into three conceptual layers:

formula definition (deterministic graph)
uncertainty modeling (input distributions and tolerances)
visualization and exploration (interactive webview)

Each layer is documented in detail in the following technical references:

1. Tolerance and range semantics

This document defines how CalcDocs interprets deterministic bounds and engineering tolerances, including:

min/max constraint propagation rules
interpretation of ± tolerances
relationship between hard bounds and probabilistic models
consistency rules across chained expressions

👉 This is the foundational layer for non-probabilistic uncertainty representation

Tolerance and Ranges (CalcDocs Docs)

2. Probabilistic modeling guide

This section formalizes how stochastic uncertainty is represented and propagated:

supported distribution families (e.g. normal, uniform, empirical)
sampling semantics used in Monte Carlo propagation
assumptions on independence between variables
handling of correlated inputs (if applicable in future extensions)
mapping between engineering intuition and statistical representation

👉 This is the core definition of the Monte Carlo uncertainty model used by CalcDocs

Probabilistic Modeling Guide (CalcDocs Docs)

3. Interactive formula viewer architecture

This document describes the runtime behavior of the system:

dependency graph construction
incremental recomputation strategy
webview update model (diff-based vs full recompute)
caching strategy for sampled evaluations
responsiveness constraints in VS Code extension context

👉 This is the implementation layer connecting model → UI

Interactive Formula Viewer (CalcDocs Docs)

Conclusion

CalcDocs extends formula documentation with an explicit uncertainty model embedded directly in the development workflow.

The main design choice is to treat uncertainty not as post-processing, but as a first-class element of the calculation graph.

This makes it suitable for engineering environments where:

assumptions evolve continuously
traceability matters
and reproducibility is required across long-lived projects

Repository

Firmware Calculations Are Invisible — So I Built CalcDocs for VS Code

Gian Michele Pasinelli — Wed, 27 May 2026 11:33:41 +0000

Every embedded project eventually accumulates “hidden math”.

Not complex algorithms.

Just hundreds of tiny engineering calculations scattered across:

macros
scaling constants
ADC conversions
timer formulas
configuration headers
lookup tables
spreadsheets
comments
old documentation

And over time, nobody remembers where the numbers actually come from.

The Problem Isn't Complexity. It's Visibility.

A firmware project may contain code like this:

#define PWM_FREQ      20000
#define TIMER_CLK     170000000
#define PWM_PERIOD    (TIMER_CLK / PWM_FREQ)

The calculation is technically simple.

But understanding it still requires mental parsing, context switching, and manual evaluation.

Now multiply that by:

multiple abstraction layers
chained macros
unit conversions
integer scaling
safety margins
hardware-specific constants
formulas real-time resolver

Eventually the firmware becomes full of numeric logic that engineers can no longer see directly.

That was the frustration behind CalcDocs.

What Is CalcDocs?

CalcDocs is a VS Code extension that turns engineering calculations into live, inspectable objects directly inside the editor.

Instead of treating formulas as passive text, it evaluates and visualizes them in context.

Example:

#define PWM_PERIOD    (TIMER_CLK / PWM_FREQ)   // 8500

No spreadsheet.

No calculator.

No mentally simulating the preprocessor.

Just immediate feedback where the calculation actually lives.

What It Can Do

CalcDocs currently supports:

inline formula evaluation
C/C++ macro expansion
live computed values
engineering formulas in YAML
dimensional/unit validation
symbol dependency resolution
inline calculations inside comments
interactive formula visualization
hybrid static analysis

The goal is not to replace firmware code.

The goal is to make engineering intent visible again.

Why This Matters in Embedded Systems

Embedded software often sits in a strange middle ground between:

software engineering
electronics
physics
control systems
industrial constraints

A single incorrect scaling factor can silently propagate across an entire system.

And the worst bugs are often not algorithmic bugs.

They're interpretation bugs.

Examples:

wrong unit assumptions
invalid conversion factors
outdated spreadsheet formulas
mismatched documentation
stale calibration constants
copy-pasted numeric logic

Most of these issues are fundamentally visibility problems.

The Spreadsheet Problem

In many companies, engineering knowledge slowly migrates outside the firmware repository.

The code contains one version.

Excel contains another.

Documentation contains a third.

Eventually nobody fully trusts any of them.

CalcDocs started as an attempt to reduce that fragmentation.

The idea is simple:

keep formulas close to the code, but make them understandable like documentation.

Interactive Formula Exploration

One of the most interesting additions was the interactive formula viewer.

Instead of only displaying final values, formulas can now be explored dynamically inside VS Code.

This becomes extremely useful during:

debugging
calibration
signal analysis
parameter tuning
validation activities

Especially when formulas intentionally remain symbolic during development.

Under the Hood

CalcDocs combines several layers:

expression parsing
AST evaluation
macro expansion
lightweight static analysis
symbol tracking
unit-aware computation
VS Code integration

The difficult part isn't evaluating formulas.

The difficult part is matching how real firmware projects are structured.

Why I’m Exploring This Area

I work mostly on:

embedded firmware
Cortex-M systems
industrial/IoT devices
RTOS-based applications
developer tooling

Over time I realized many embedded workflows still depend heavily on:

tribal knowledge
disconnected spreadsheets
manual verification
implicit assumptions

I think tooling around engineering visibility is still massively underexplored.

Future Directions

Some areas I’m currently exploring:

stronger dimensional analysis
cross-file dependency graphs
richer interactive webviews
symbolic computation
tighter integration with documentation
formula traceability
engineering validation workflows

Final Thought

Most firmware calculations are not difficult.

They're just hidden.

CalcDocs is an attempt to make embedded engineering knowledge visible directly where it matters most: inside the code.

If you work on embedded systems, I’d genuinely be interested in how your team handles:

formulas
scaling factors
engineering constants
unit conversions
spreadsheet dependencies

because every company seems to reinvent this differently.