Resource Models

What a resource model is

Resource Analysis Tools measures utilization, specifically counters of quantities of resource types, from a synthesis report. A ResourceModel predicts the resource utilization based on a hardware models configuration. For example, in an Xilinx / AMD FPGA flow, it can predict the number of FF, LUTs, or BRAM based on a hardware module’s parameters such as the bitwidths or buffer sizes. This predictio enables design-space exploration to price thousands of configurations from just a handful of syntheses.

What you write

To add a resource model to a HwModule class, you generally need to write the function: def get_rm(platform) to provide a model for a specified platform.

Once get_rm(platform) function is specified, the HwModule’s functions predict and compose can be used to predict the resource consumption of a HwModule and its hierarchy of modules contained by it.

Every module has a model. Returning None does not mean “unmodelled” — it means the default lookup, a model whose parameters are the measurements themselves. That is the right answer more often than it looks: a lookup assumes nothing about the shape of the cost function, so no structural assumption can be wrong, and it is exact at every configuration it has seen.

Model types

Three kinds, each with a page of its own. They differ in what they trade for an answer:

kind	how it answers	costs you
LookupResourceModel	recalls the measurement for exactly this configuration; refuses to interpolate	one synthesis per point you will ask about
VitisResourceModel	prices countable structure by device rule, regresses the rest	a structure declaration, and a basis you have to choose
InterfaceResourceModel	recalls what a composite costs beyond its sub-modules	nothing — it is read from records the sweep already filed

The first and third are the same machinery: an interface model is a lookup, keyed on the composite’s boundary instead of on a module key. What differs is the quantity it recalls, not the method.

So the only real choice is the second row, and it is about coverage, not sophistication. Reach past a lookup when the parameter space is too large to enumerate, and accept some bias in exchange for answering points you never measured.

What a confidence is

A bare number invites an exploration to optimize into a region nothing ever measured. So a prediction is never just counters: every model returns a Confidence beside them.

level	means
EXACT	the model’s form reproduces every calibration point with zero residual — a checked claim, not an approximation
INTERPOLATED	the query lies inside the region the model was calibrated over
EXTRAPOLATED	outside it. The level that matters most here, because what you cross on the way out is usually a regime boundary — and those move several counters at once
UNCALIBRATED	no fit backs this number

Two properties are worth knowing because they are what make the level trustworthy rather than decorative:

A composed estimate reports its weakest link, not its average. If three modules are exact and one is extrapolated, the total is EXTRAPOLATED — and it names which module, which is what you would go and measure first. An estimate that averaged its confidences would read as fine while resting on the one number nobody checked.

A model that has not seen a configuration says so. A lookup asked about a point it does not hold reports UNCALIBRATED rather than returning its nearest entry. That refusal is the design, not a gap in it: a plausible wrong number is worse than an admitted absence, because only one of the two gets investigated.

In this section

Simplest first — each page has one job.

1. What a ResourceModel is — a CalibModel whose targets are the platform’s counters: the methods, what counters are, and why the component-facing entries take a component rather than a feature vector.
2. The lookup model — the simplest one, and the default: recall a measurement, refuse to interpolate. With a runnable example.
3. Binding a model to a design — get_rm, and why it is a classmethod.
4. VitisResourceModel — the model that derives: resource_structure field by field, the rule each primitive is priced by, and how to choose the basis LUT and FF are fitted on.
5. The interface model — a composite’s own cost, keyed on its boundary: why that is the right key, and why it is a lookup rather than a fit.
6. Predicting — predict, compose over a hierarchy, and reading the confidence.
7. Fitting — corpus, basis, load_or_fit, and validating held-out.
8. Resource measurements — attributing a csynth report to the modules that caused it, the two traps that otherwise corrupt the numbers, and the InspectSynthStep build rung.

A fully worked instance, built and measured end to end, is the VecMult example; the advanced case — a composite, with state and an interface term — is the block FIR.

See also

• Model calibration — the shared base these models are built on: the CalibModel shape, the corpus format, the confidence levels and the model kinds.
• Resource Analysis Tools — where the measurements these models are built from come from.
• Timing Models — the same role on the other axis.

---

Table of contents

• What a ResourceModel is - The interface every resource model implements — a CalibModel whose targets are the platform's counters: get_params extracts what the corpus records, transform derives features, then predict and confidence. What counters are and why you do not define them, and which model kind to reach for. Most designs implement none of these methods — they pick a kind and let it do the work.
• The lookup model - The simplest model: resource usage looked up directly from prior synthesis results for exactly those parameter values. State which resource types to store, fit it on measured points, and it answers EXACT for a configuration it has seen and UNCALIBRATED for one it has not. It does not interpolate, and that is deliberate.
• Binding a model to a design - How a model gets attached to a design: one classmethod, get_rm(platform), returning a model or None for the default lookup. It is a classmethod on purpose — a model must not close over an instance, and having no self makes that impossible rather than merely discouraged. The base caches the result per (class, platform).
• VitisResourceModel - The default model kind for an AMD/Xilinx target, field by field. A design declares what it contains as a DesignStructure: multiplier groups and partitioned arrays, which device rules price exactly with no free parameters, plus a LutFfBasis naming the quantities LUT and FF are allowed to grow in. Includes how to choose those terms — when you need LW, when you need LW-squared, and when the log2 refinement earns its keep — and how the fit holds out both the counted part and the regimes a counter has no rule for.
• The interface model - What a composite costs beyond the sum of its sub-modules — the m_axi adapters, inter-task FIFOs, control block and DATAFLOW shell. It is a LookupResourceModel keyed on the boundary signature rather than the module key, because that is what the term was measured to depend on: invariant across compute parameters, moving only when the ports changed. A lookup rather than a fit is a statement about the evidence, and the term is never clamped at zero.
• Predicting - Getting a number out: predict for one module, compose for a hierarchy. The composition rule is one line applied recursively — a module's own cost plus the sum of its children — where a composite's own cost is the interface term, and that term is defined exactly as a synthesis report measures it. Every estimate carries the weakest confidence that fed it, and names the modules sitting at it.
• Fitting - Determining a model's free parameters from measurements, on the resource axis. Where the data is stored (records filed per module key, promoted from an untracked work tier into a committed library), how a sweep produces it, how load_or_fit resolves a published artifact before a corpus, and why installing a model and calibrating one are separate acts. The shared machinery lives in the calibration guide; this page is the resource-specific path through it.
• Resource measurements - Filing resource measurements as calibration data: the InspectSynthStep build rung that attributes a csynth report and stores the per-module records, how synthesis cost is recorded rather than modelled, and how to sweep a parameter grid so the library accumulates. The analysis mechanics — reading the report and decomposing a composite — are in Resource Analysis Tools; this page is about keeping the results.