Uncertainty and learning

Supply chain decisions are made under uncertainty. Demand is noisy, lead times drift, and costs change. Envision reflects that reality by treating uncertainty as data, not as an afterthought. This page explains how ranvars, zedfuncs, Monte Carlo, and differentiable programming fit into the language.

Table of contents

Uncertainty is part of the model, not a parameter

In many tools, uncertainty is represented by a small set of parameters or hidden inside a forecast. In Envision, uncertainty is explicit and first class. A ranvar is a probability distribution over integers. It can be added, combined, and passed through functions just like a number. That design keeps the uncertainty visible throughout the calculation instead of compressing it early.

// A demand distribution and its summary statistics.
base = poisson(5)
expected = mean(base)
q90 = quantile(base, 0.9)

show scalar "Expected demand" with expected
show scalar "P90 demand" with q90

The point is not the specific functions, but the fact that the distribution remains available. You can use the mean when you need a single value, but you do not lose the underlying shape.

Ranvars are discrete by design

Ranvars are defined over integers because most supply chain decisions are discrete: units, orders, days, or batches. This may seem limiting, but it is an accurate reflection of operational reality. It also provides computational advantages, because discrete distributions can be represented exactly and combined efficiently.

If you need continuous behavior, you can often represent it by scaling the unit. For example, you can model lead time in half-days by doubling the unit, or model weight in tenths by multiplying by ten. The key is to keep the modeling choice explicit so that readers know what a unit means.

Combining distributions keeps risk visible

The main benefit of ranvars is that you can combine them without collapsing uncertainty. Adding two ranvars produces a new distribution. Taking a max or applying a transformation produces another. This allows you to carry uncertainty through multiple stages: demand plus lead time, demand minus inventory, or demand after promotions. The uncertainty stays visible all the way to the decision rule.

This is a different mindset from classic forecasting workflows where the distribution is summarized to a single number early. Envision encourages you to delay that reduction until the last possible moment.

Risk measures are explicit choices

Once you have a distribution, you must decide how to act on it. That decision is not purely technical; it is a business preference. Do you optimize for the mean? For the 90th percentile? For expected profit after penalties? Envision does not hide this choice. It gives you tools such as quantile, fillrate, or crps, but you are responsible for deciding which measure reflects the business trade-offs.

This explicitness is a strength. It prevents the model from silently optimizing for the wrong risk measure. It also makes policy review easier because stakeholders can see which risk attitude is encoded in the script.

Zedfuncs capture value curves

Some decisions are not about uncertainty but about value. A zedfunc is a numeric function defined over integers. It is useful for representing curves such as stock reward, price breaks, or penalty costs. Unlike a table, a zedfunc is continuous over its support, which makes it a natural tool for optimization.

// A simple value curve: increasing value with diminishing returns.
value = linear(1) + 5
v3 = valueAt(value, 3)

show scalar "Value at 3" with v3

The syntax is compact, but the modeling implication is large: you can carry a value curve through a calculation without reducing it to a single point until the end.

Monte Carlo is controlled randomness

Monte Carlo simulation is a way to test decisions under uncertainty. Envision includes a montecarlo block to express that explicitly. The block repeats a computation a fixed number of times and lets you aggregate across iterations with sample.

// Estimate the average of a noisy demand.
montecarlo 1000 with
  d = random.poisson(5)
  sample avgDemand = avg(d)

show scalar "Average demand" with avgDemand

The important design choice is the fixed number of iterations. Monte Carlo is costly, so the script must make the cost visible. This keeps simulations predictable and prevents accidental runaway compute.

When to use Monte Carlo versus ranvars

Ranvars are exact when the operations are supported by the language. Monte Carlo is a fallback when you need to simulate behavior that is difficult to express analytically. A common example is a complex policy that has thresholds or constraints that depend on multiple uncertain inputs. In those cases, Monte Carlo can approximate the outcomes without requiring a closed form distribution.

The important trade-off is compute cost. Monte Carlo results improve with more iterations, but each iteration is work. Envision forces you to declare the count explicitly so that the cost is visible in the script itself.

Sampling is not a replacement for structure

Monte Carlo can be seductive because it is flexible, but it should not replace structural modeling. If a relationship can be expressed with tables and ranvars, that representation is usually faster and more transparent than simulation. Simulation is best reserved for scenarios where the structure is too complex to express directly or where you need to stress test a decision under extreme randomness.

This distinction matters for explainability. A ranvar-based calculation can be inspected and reasoned about. A Monte Carlo result is an estimate, and it requires explanation about variance, confidence, and the number of iterations. The model author should decide which is appropriate for the audience.

Learning is part of the language

Envision includes differentiable programming for fitting models directly inside a script. This is not a general machine learning framework; it is a focused tool for tuning parameters in a decision model. Because it lives in the same script, the learning objective and the business logic remain aligned.

table Obs = with
  [| as X, as Y |]
  [| 1, 2.8 |]
  [| 2, 4.2 |]
  [| 3, 6.1 |]
  [| 4, 8.0 |]

autodiff Obs epochs:6 learningRate:0.05 with
  params a auto
  params b auto
  delta = a * Obs.X + b - Obs.Y
  return (delta^2, mae: abs(delta))

show summary "Parameters" with
  a
  b

The purpose is not to build a massive model, but to fit the parameters that matter to the decision. This keeps the learning objective close to the operational outcome.

Learning and optimization should remain aligned

In many pipelines, a model is trained elsewhere and then imported into a decision script. That can create a disconnect between what the model optimizes and what the business actually needs. Envision reduces that gap by allowing learning to happen inside the same script that produces decisions. You can optimize parameters directly against the operational objective, not just against a statistical metric.

This alignment is especially valuable for supply chain, where the objective is rarely a pure forecast error. It might be a balance between shortage penalties, holding costs, and service levels. By keeping learning close to the decision, you can tune the model for the outcome that matters.

Constraints keep learning realistic

Envision lets you bound parameters in autodiff, which is more than a numerical trick. It encodes business realities. Prices cannot be negative, lead times cannot be zero, and service levels must remain within a reasonable range. Constraints prevent the learning process from drifting into solutions that are mathematically valid but operationally meaningless.

This is another example of the language aligning technical optimization with business intent. The model is not just fitting data; it is fitting data within the rules of the business.

Why explicit uncertainty improves decisions

When uncertainty is explicit, you can build policies that are sensitive to risk and not just averages. For example, a safety stock policy can use quantiles of a ranvar rather than a fixed multiplier. A price optimization can evaluate value curves rather than a single point estimate. Envision makes these approaches practical because the distributions and functions are native types, not external artifacts.

Combining uncertainty with decisions

The real power comes from combining uncertainty with value. A ranvar can be transformed into a zedfunc through reward functions, and a zedfunc can be optimized to select a decision. This is the underlying logic of many supply chain recipes: you want the decision that maximizes expected value under uncertain outcomes.

This is also why Envision avoids hiding uncertainty behind a single forecast. When you keep the distribution, you can test the robustness of a decision and decide whether it is worth the risk.

Communicating uncertainty is part of the job

A model that understands uncertainty is only useful if the uncertainty is communicated. In Envision, you can surface quantiles, service levels, or risk bands directly in the dashboard. That makes the trade-offs visible to decision makers and reduces the temptation to treat a forecast as a guaranteed outcome.

This is not only about transparency. It also helps change management, because stakeholders can see how the model behaves under different scenarios rather than trusting a single number.

Why this matters in practice

Supply chain decisions are rarely about a single outcome. They are about balancing service level, inventory risk, and cost. Envision treats uncertainty as data so that those trade-offs remain explicit all the way to the dashboard. The language is designed to keep the uncertainty visible, so that the final decision can be justified, audited, and improved over time.