IAM-AX

By

IAM-AX is a metamodel for designing, generating, inspecting and running computable general-equilibrium (CGE) models. It generates the code of integrated or non-integrated CGE models from i) structured socio-economic, technical or physical data and ii) standalone analytical equations written in Python, in a form close to what one would expect from a rigorous analytical model description.

Sewn on ImaCLIM — IMpact Assessment of CLIMate policies — whether in static or recursive settings, IAM-AX is not merely another implementation environment for applied general-equilibrium (GE) modelling. Its ambition is to define a common architecture for building, executing, testing, reading, comparing and maintaining models.

IAM-AX is also a response to the social role of models, whose vocation is to inform public reasoning and remain appropriable by anyone concerned by their use. Models with such a vocation often require a significant degree of complexity, and the problem is that the algorithmic expression of this complexity tends to degrade over time. As models are enriched, extended and adapted to new questions, technical debt, implicit conventions, fragmented workflows and ad hoc corrections tend to make their code harder to understand and control. Errors then become harder to detect, and results may be severely distorted. Given the role such models are expected to play, this kind of opacity can become hard to accept depending on what is at stake.

This is why IAM-AX seeks to push modelling transparency as far as possible. Its purpose is to prevent the elements of a modelling exercise — data, unknowns, behavioural assumptions, functional interactions, generated equations, numerical resolution and results — from being scattered across opaque code, tacit practices or undocumented conventions. By bringing these elements back to a level of explicitness and simplicity that makes opacity difficult to sustain, IAM-AX addresses the black-box syndrome often associated with complex applied models.

This ambition matters all the more in a context of widespread distrust toward technical and scientific discourse. IAM-AX treats readability, traceability and communicability not as optional documentation tasks, but as core design constraints. In doing so, it attempts to make modelling work more open to review, transmission and contestation.

The apparent simplicity of this workflow is the visible result of a substantial research and engineering effort. IAM-AX does not merely wrap existing modelling practices in a convenient interface. It transforms a data-defined, object-oriented and user-extensible analytical description into a functional, differentiable and solver-compatible numerical system. The core R&D challenge is therefore to preserve the modeller’s freedom at the analytical level while controlling the computational consequences of that freedom.

In that sense, IAM-AX is both a model reader and a model generator. Like a reader able to interpret many discs encoded in the same format, IAM-AX can interpret many models as long as they follow its common grammar. It then generates explicit, readable Python code corresponding to the model it has interpreted. A model is no longer only a bespoke codebase. It becomes an object that can be read, inspected, compared and maintained according to shared rules.

A common modelling grammar¶

What IAM-AX does¶

_

IAM-AX generates the executable Python code of a computable general equilibrium (CGE) model from two ingredients: a structured data file and a library of reusable analytical equations. Once generated, this code is compiled, run and solved to produce the results classically expected from applied general-equilibrium modelling.

The data file, usually in XLSX or XLSM format, may contain socio-economic accounts, technical coefficients, physical quantities, prices, taxes, margins and other data, represented either as cross-sectional datasets or as time series. The library.py file contains the analytical equations of the model, written as Python classes and methods in a form that remains close to a traditional analytical description.

In most workflows, completing the analytical description of a model says little about the time still required to implement it computationally. IAM-AX is designed to close that gap.

Model grammar¶

_

IAM-AX relies on an ontology that embeds the specification of a modelling exercise directly into the structure of data. Input data are not treated as passive numerical material: they actively participate in defining what the model is, what it solves and how its components behave.

The basic interacting objects of a model are represented as entities. Such entities may stand for sectors, goods, resources, persons, macroeconomic identities or any other object whose dynamics and interactions can be expressed mathematically.

Behavioural interdependencies between entities, time structures and resolution spaces are all expressible through structured data. The data file does not merely feed the model; it helps constitute it.

This grammar is central to the originality of IAM-AX. It shifts part of the model specification from handwritten code to structured, inspectable data. That shift is powerful, but technically demanding: once data become part of the model’s grammar, the software must be able to interpret them, check them, connect them to analytical functions and translate them into a coherent numerical system.

Data unknowns¶

_

A distinctive feature of this grammar is that unknowns are declared directly in the data. Symbols such as ?(t=0), ?(t>0) or ?(t=t') indicate values that are unknown for calibration or recursion purposes.

In many classical CGE workflows, the partition between endogenous and exogenous variables is defined in the modelling code. In IAM-AX, that partition is declared at the data layer, and IAM-AX formulates the corresponding resolution programme automatically.

This localization has a practical consequence: by changing which cells carry unknown markers, users alter the resolution space without modifying any code. A value can be known in one sector and unknown in another, fixed for one period and solved for another.

This possibility is simple from the user’s perspective, but it is not simple computationally. IAM-AX must infer from these markers the set of unknowns, the corresponding root conditions, the calibration problem and the shape of the numerical system to be solved. The flexibility of the data layer therefore creates a demanding inference meta-problem inside the software.

Functional choices¶

_

The model’s behavioural structure is also selected through the data file. A dedicated sheet specifies which functions, defined in library.py, govern the interactions between entities.

Users can therefore vary not only numerical trajectories and unknown specifications, but also the explanatory mechanisms themselves: production functions, preference structures, market closures and behavioural rules.

Together, the unknown markers and the functional selection sheet form the data grammar through which model structure is assembled. The model is not frozen in code; it is constituted from structured data and reusable behavioural functions.

This is one of the reasons why IAM-AX required a substantial amount of R&D. Each functional choice modifies the dependency structure of the generated model. The software must therefore assemble different computational graphs from the same general infrastructure, while preserving consistency of dimensions, compatibility with calibration, differentiability and solver readiness.

Project layer¶

_

An IAM-AX modelling project is organized around three components: a data file, a library.py and a worker script.

The data file defines the economic objects, their dimensions, their known or unknown values, and the behavioural functions selected to govern their interactions. The library.py file contains the analytical descriptions of those behaviours: production and preference structures, market mechanisms, dynamic components and other user-defined relations. The worker script launches modelling exercises and provides an object-oriented interface for exploring and comparing results.

This organization separates data, analytical content and execution logic. IAM-AX takes these three inputs and generates the functionally pure Python model that is compiled and solved.

Matrices as code¶

_

IAM-AX extends the input-output convention beyond values and volumes. Standard input-output tables represent interdependencies in economic systems through matrices of flows. IAM-AX applies this logic to a broader range of model-relevant objects: prices, taxes, excises, exonerations, margins, rents, rates and physical quantities, etc.

Interdependence matrices therefore become a modelling language: a way to encode the structure of an economic system, the objects it contains and the relationships through which they interact. This representation remains compatible with national accounting conventions while allowing richer specifications when the research question requires them.

Model library¶

_

Users define their behavioural functions by editing library.py. These functions are written as Python classes and methods. Because each function is an identifiable Python object, functions can be added, tested, compared and replaced without rewriting an entire model.

IAM-AX relies on strict naming conventions to determine how each method contributes to the model. Methods such as x_computer, x_rooter or compute_calibrand_<i> tell the software whether a given function computes a variable, defines a root condition or participates in calibration.

These conventions impose a modelling discipline. Behavioural assumptions are embodied in identifiable, reusable objects rather than dispersed across long, evolving equation files. The result is a short distance between analytical reasoning and executable code: equations are written close to their analytical form, while IAM-AX assembles the computational graph by connecting them with the relevant operands and shapes.

Operands and shapes¶

_

IAM-AX expresses model operations in terms of operands and shapes. Based on the structure declared in the data, the software determines which vectors, matrices or tensors to pass to each user-defined method.

This creates a bridge between the economic objects in the data, the analytical functions in library.py, and the generated model that is compiled and solved. The modeller defines components; IAM-AX connects them consistently across entities.

The structure of operands matters as much as their values, because the model is not only a numerical object. It is a structured system of named quantities whose dimensions must be aligned, interpreted and transformed consistently throughout the computation.

From grammar to computation¶

Computational consequences¶

_

The modelling grammar described above gives users considerable freedom. They can change unknowns, select behavioural functions, alter closures, modify calibration targets, vary sectoral decompositions and explore alternative assumptions from the data layer and the analytical library.

This freedom has direct computational consequences. IAM-AX must indeed be able to generate many structurally distinct models from the same architecture. Each generated model may have a different set of unknowns, a different dependency graph, different tensor shapes, different calibration requirements and different derivative structures.

The engine is therefore not a secondary implementation detail. It is the part of IAM-AX that makes the grammar operational. Its role is to transform a flexible, readable and user-extensible model description into a system that can be compiled, differentiated, solved, inspected and reused.

JAX¶

_

IAM-AX is built on JAX, whose name refers to Autograd and XLA — Accelerated Linear Algebra. This gives the software access to automatic differentiation, XLA compilation, vectorization and efficient matrix operations.

Automatic differentiation allows algorithmic sensitivities of model outputs to be computed with respect to any input parameter or combination of parameters. This supports a more systematic exploration of model structure: which assumptions matter, where sensitivities lie, and how policy scenarios propagate through the system.

JAX is therefore a crucial foundation, but it is not in itself the solution. The technical challenge is to make JAX usable for models whose structure is generated from data, whose equations are written as object-oriented Python methods, and whose dimensions and unknowns can vary across modelling exercises. Much of the R&D behind IAM-AX consists in building this bridge between a modeller-friendly grammar and a differentiable compilable backend.

From model to code¶

_

Generating executable code from high-level modelling ingredients requires more than concatenating equations. Given structured data, a functional selection sheet and a library.py, IAM-AX must infer which objects are computed, which are rooted, which are calibrated, which values are known, which are unknown, which behaviours are activated and how all dependencies propagate across dimensions and time. This code-generation step is where the model moves from a readable analytical description to an executable computational system.

The central challenge is to preserve the readability and modularity of user-defined economic behaviours, while transforming them into efficient, differentiable, compilable numerical systems.

This step is also where IAM-AX’s technical contribution becomes most visible. The software must produce code that remains understandable to a human reader, while also satisfying the stricter requirements of numerical resolution: pure functional transformations, stable shapes, traceable dependencies, differentiable operations and solver-compatible root conditions.

OO meets JAX¶

_

A difficulty is that the two programming disciplines involved do not naturally fit together. IAM-AX exposes economic behaviours through object-oriented programming: users define classes, methods and reusable components in a modular, readable form close to economic reasoning.

JAX, by contrast, requires a functional programming discipline: pure functions, immutable transformations, traceable computation graphs and array-based operations compatible with automatic differentiation and XLA compilation.

IAM-AX must make object-oriented economic modelling compatible with JAX’s purely functional programming paradigm. This reconciliation is one of the core technical achievements of the software.

Tensor mapping¶

_

Behind the code-generation step, model components must be mapped to tensors, matrix slices and structured operands across entities, sectors, products and time periods, with an additional vectorization-friendly axis.

This requires advanced indexing in three or four dimensions and careful control of shapes, broadcasting rules, localization conventions and alignment mechanisms. What appears to the user as a named economic object is internally translated into precisely indexed numerical operations.

This mapping is a large part of the software’s hidden difficulty. It is not enough to know that a function should apply to a sector, a product or a period. IAM-AX must determine where the relevant quantities are located, how their dimensions relate to one another, how they should be batched or broadcast, and how the resulting operations should remain compatible with automatic differentiation and solver routines.

Versatility and performance¶

_

The modelling grammar introduces a tension that has direct computational consequences. Because users can change the localization of unknowns, modify calibration targets, select different behavioural functions and alter functional interactions between entities, IAM-AX must be able to generate many structurally distinct models from the same infrastructure. A general-purpose model generator cannot rely on a single hand-optimized layout: it must interpret data, assemble the computation graph, connect user-defined behaviours, infer dimensions and build derivative objects for each generated model.

Earlier versions of IAM-AX were usable in projects involving open monadic economies, but compilation and execution costs grew too quickly with the number of sectors. This limited the move toward larger sectoral decompositions and multiregional applications. The performance problem was not simply that some numerical routines were slow; it was the structural consequence of versatility: how to generate many possible models while containing the space complexity of their underlying minimization problem.

The subsequent optimization work addressed this tension at several levels.

First optimization layer¶

_

A first optimization layer reduced both compilation and runtime costs without narrowing the expressive power of the grammar. This included pruning the computation graph passed to the solver, mobilizing open-source solvers for large-scale numerical optimization, disaggregating formerly scalar Lagrangian components, vectorizing user-provided functions, redesigning computations around sparse data and reducing the memory footprint of derivative objects by inferring and exploiting their sparsity structure. The most substantive changes concerned vectorization, sparsity and solver design.

Vectorization addressed a specific XLA cost. When a large model is assembled naïvely from many user-defined components, each component triggers a separate compilation trace. Vectorizing user-class methods replaces this pattern with a single compiled trace over a batched dimension, reducing compilation cost superlinearly.

Sparsity appears at two distinct levels: in the data structures manipulated by the model, and in the derivative structures generated by automatic differentiation. Both require dedicated machinery, because JAX does not natively provide, in a mature and directly usable form, all the sparse abstractions IAM-AX requires. IAM-AX therefore uses data-aware sparse representations and indexing strategies that reduce the number of stored values. Dedicated routines handle sparse storage, localization, reshaping, broadcasting, aggregation and densification of model operands.

For derivative computation, IAM-AX uses automatic differentiation to obtain Jacobian and Hessian matrices. These matrices are typically structurally sparse, because most variables depend directly on only a limited subset of other variables. IAM-AX infers and exploits the resulting sparsity patterns by identifying non-zero blocks, reducing redundant derivative computations, preserving block structure and exposing derivative information in a form compatible with the solver interface.

These optimizations are not peripheral performance improvements. They are what allow a general model generator to remain usable when models grow in structural diversity and size. Without this layer, the expressive power of the grammar would quickly become computationally prohibitive.

Graph lifting¶

_

The first optimization layer improved performance within the existing structure of the generated problem. A further step was needed to improve performance at a deeper level: reducing the problem’s dimensionality before it reaches the solver.

Graph lifting addresses this by dynamically rearranging the computation graph to identify unknowns whose values can be expressed symbolically from the structure of the model. IAM-AX transforms the computation graph into a symbolic representation, analyses multivariate dependencies between variables, and constructs deterministic computation trees for analytically expressible unknowns. These trees may depend not only on known quantities, but also on other unknowns that remain in the numerical problem. IAM-AX then removes the analytically expressible unknowns from the root-finding problem and reconnects their computation trees to the remaining computational graph.

The resulting gain differs in kind from those achieved at the first layer. The software no longer merely compiles faster, stores less or evaluates derivatives more efficiently: it reduces the size of the numerical problem itself, improving both speed and numerical conditioning.

This is a particularly important R&D contribution because it acts on the generated model’s structure rather than only on its compilation and execution. IAM-AX uses information about dependencies to simplify the mathematical problem before numerical resolution. This turns model generation into a form of structural analysis, not only code production.

Caching and reuse¶

_

A generated model involves expensive compilation, derivative construction, sparsity analysis and graph transformations. IAM-AX therefore provides mechanisms for caching, serialization and reuse of costly intermediate objects across modelling runs.

Applied modelling is rarely a one-shot exercise. Users run variants, compare scenarios, adjust assumptions, modify data, test closures and inspect sensitivities. Reusing safely reusable compiled objects keeps exploratory modelling responsive without sacrificing the generality of the generator.

This layer matters because it reflects the actual practice of modelling. IAM-AX is designed not only for producing one result, but for supporting iterative research, debugging, comparison and sensitivity analysis. Caching and reuse therefore connect the technical architecture of the software to the practical rhythm of applied modelling work.

Optimal versatility¶

_

The central technical challenge of IAM-AX is to make a highly flexible modelling grammar feel simple to use while preserving the desirable properties of carefully handwritten models. Users should be able to change data, unknowns and/or behaviours without rewriting numerical code. At the same time, the generated model must remain differentiable, compilable, efficient, inspectable and compatible with solvers.

Such reconciliation explains the amount of research and development required. IAM-AX needed mechanisms for interpreting model structure from data, translating object-oriented analytical functions into functional computational graphs, aligning tensor shapes, reducing derivative costs, lifting graphs, caching reusable objects and preserving readability in the generated code.

The software’s user-facing simplicity is therefore not a sign that the problem is simple. It is the result of moving complexity into the model generator, where it can be organized, tested and made reusable.

Standard and transparency¶

No black box¶

_

Even a moderately non-trivial CGE model is difficult to appropriate from the outside. When it becomes part of an integrated assessment architecture, the black-box perception becomes nearly unavoidable.

Beyond perception, there is a structural risk. As models are enriched over time, they tend to accumulate patches, legacy assumptions, disabled blocks and undocumented closures. A model that has grown through many hands and many years too often becomes dependent on tacit knowledge held by a small number of people, and/or produces plausible results while being silently corrupted by accumulated inconsistencies.

IAM-AX addresses this by enforcing readability as a design constraint of the software. IAM-AX shifts the inherent complexity of these modelling exercises upstream to the model-generating process, so that the generated modelling code is perfectly readable. The aim is to make the black-box perception structurally impossible rather than merely discouraged.

Note that this does not mean that all complexity disappears. It means that complexity is moved to a layer where it can be organized according to stable rules, while the model that gives form to a specific research question is fully written from scratch, instead of degrading at the rate of its complexification.

Model standard¶

_

IAM-AX establishes a standard for what a model is expected to contain and how it is expected to be organized: structured data, named operands, explicit unknowns, class-based analytical definitions, data-level functional selections, declared calibration conventions and a readable generated Python model.

The strictness of these conventions is part of the scientific value of the software. A model should not only run; it should be readable, explainable and reviewable by construction. This makes comparisons across users, projects and institutions meaningful, because different models share a common grammar rather than being structurally incommensurable artefacts.

Scientific scrutiny becomes a productive entry point rather than an obstacle: doubt about results can be traced back through the generated model to its data and behavioural components.

Core difference¶

_

IAM-AX is not an alternative language for writing CGE models. It is a modelling infrastructure: a system in which data constitute the model specification, a shared grammar defines what models are made of, a differentiable engine generates and solves them, and the result at each layer remains inspectable.

Its contribution is not only computational. It is methodological and institutional: it reduces the dependence of complex modelling work on tacit knowledge, limits vulnerability to software ageing, and makes models communicable across teams, disciplines and generations of users.

IAM-AX is therefore best understood as a software infrastructure for building transparent, auditable and maintainable general-equilibrium models.

The tables below show how IAM-AX differs from competing relevant modelling environments in several respects.

Table 1 Close CGE and economic-modelling neighbours¶
Capability	IAM-AX	GAMS	GEMPACK	MPSGE	RunGTAP	Dynare
GE/CGE focus	✔️	general algebraic	✔️	✔️	✔️	DSGE-oriented
High-level formalism	✔️	✔️	✔️	✔️	GUI layer	✔️
Data/model separation	✔️	✔️	✔️	✔️	✔️	✔️
Derivatives/Jacobians	✔️	✔️	✔️	✔️	✔️	✔️
Sparse derivatives	✔️	✔️	✔️	via PATH/MCP	✔️	model-specific
Inferred derivative sparsity	✔️	solver-side	TABLO-linearized	via PATH/MCP	TABLO-linearized	symbolic/block
Sparse large-scale solving	✔️	✔️	✔️	✔️	✔️	DSGE-specific
Closure control	✔️	❌	✔️	❌	✔️	❌
Data-specified unknowns	✔️	❌	❌	❌	❌	❌
Data-selected behaviours	✔️	❌	❌	❌	❌	❌
Structural simplification	✔️	presolve	condensation	solver-side	inherited	✔️
Symbolic transformations	✔️	limited	TABLO-based	limited	inherited	✔️
Graph lifting of unknowns	✔️	❌	❌	❌	❌	❌
Ageing-immunized code	✔️	❌	❌	❌	❌	❌
Instant model re-specification	✔️	❌	❌	❌	❌	❌

Table 2 Broader modelling and optimization frameworks¶
Capability	IAM-AX	AMPL	AIMMS	Pyomo	JuMP	CasADi	MTK.jl	OpenMDAO
Data/model separation	✔️	✔️	✔️	script/API-level	script/API-level	graph/API-level	script/API-level	component/API-level
Derivatives/Jacobians	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️
Sparse derivatives	✔️	✔️	partial	solver/AD	✔️	✔️	✔️	✔️
Inferred derivative sparsity	✔️	solver-side	solver-side	AD-dependent	✔️	✔️	✔️	component partials
Data-specified unknowns	✔️	❌	❌	❌	❌	❌	❌	❌
Data-selected behaviours	✔️	❌	❌	❌	❌	❌	❌	❌
Generated code	✔️	solver export	solver export	solver export	solver export	✔️	✔️	limited export
Structural simplification	✔️	presolve	solver presolve	preprocessing	solver presolve	graph opt.	✔️	workflow-level
Symbolic transformations	✔️	limited	limited	limited	limited	✔️	✔️	workflow-level
Graph lifting of unknowns	✔️	❌	❌	❌	❌	❌	ODE/DAE only	❌
Ageing-immunized code	✔️	❌	❌	❌	❌	❌	❌	❌
Instant model re-specification	✔️	❌	❌	❌	❌	❌	❌	❌

_{The comparison is deliberately architectural rather than evaluative. A ✔️ does not mean that all tools implement the same mechanism. A ❌ means that the feature is not provided as a native architectural mechanism, even if related effects can sometimes be obtained through scripts, solver-side transformations, generated instances, model-building conventions or domain-specific workflows. In GEMPACK, "condensation" refers to a reduction of the linearized system before solving, with eliminated variables recovered afterwards. For CasADi, "graph opt." refers to symbolic graph optimization rather than full equation-system structural simplification in the ModelingToolkit sense. "Closure control" means native support for changing the closure of a model as part of the modelling environment, rather than hand-coded changes to the model, equation set, fixings or scripts. For MTK.jl, "ODE/DAE only" indicates that the relevant variable-introduction and structural-transformation mechanisms are tied to ODE/DAE system analysis.}

In short

IAM-AX is a (model) reader; each model is a disc; the data and analytical library define what is written on the disc; and the generated Python code is the explicit readable form of the interpreted model.

This standardization is what makes IAM-AX distinctive. It turns model building from a collection of bespoke codes into a reproducible modelling ecosystem.

The computational machinery is organized behind the modelling standard for user comfort, while the generated model remains visible for auditability. Complexity is not concealed in the sense of a black box; it is structured and displaced. The quality of the generated code then becomes a check on the soundness of the generation process itself.

IAM-AX should therefore be read as both a modelling grammar and the result of a substantial R&D effort, whose promise is not only to run complex models, but to make their construction and maintenance possible under shared rules.

API Documentation

iamax

Reference Documentation