Consumer Theory Crate
Provides core tools for consumer-theory analysis over bounded consumption bundles.
Overview
The crate is organised around three main tasks:
- validating and evaluating consumer preferences
- tracing indifference curves in two dimensions
- solving for utility-maximising bundles under a budget constraint
These capabilities are exposed through the pref, indifference, and marshallian
modules.
Preference Modelling
The pref module defines Preference, which represents a utility function over a
bounded bundle of goods.
A preference instance supports:
- utility evaluation with
get_utility - marginal utility estimation with
get_mu - marginal rate of substitution evaluation with
get_mrs - optional validation against continuity, monotonicity, and convexity checks at construction time
Validation uses deterministic boundary points together with Sobol-sequence sampling to test the supplied utility function over the admissible region.
Indifference Curve Tracing
The indifference module provides trace_2d, which traces an indifference curve for a
target utility level in the plane of two selected goods.
The procedure:
- fixes all non-plotted goods at the midpoint of their bounds
- grids one selected good across its bounds
- uses bisection to solve for the second selected good
This is useful for inspection, plotting, and sanity-checking preference behaviour in two-good slices of a higher-dimensional problem.
Marshallian Bundle Optimisation
The marshallian module provides optimal_bundle, which solves for the
utility-maximising bundle subject to a linear budget constraint.
The optimisation uses an interior-point log-barrier method with:
- a strictly interior starting point
- numerical marginal utility estimation
- backtracking line search
- configurable outer and inner iteration limits
This produces a constrained optimum for problems of the form p * x <= income.
Shared Standard Configuration
The crate maintains a shared standard configuration that supplies default settings for:
- preference validation and numerical evaluation
- indifference-curve tracing
- bundle optimisation
These defaults are grouped under StandardConfig as:
preferenceindifferenceoptimisation
This allows callers to adjust standard behaviour centrally while keeping per-call configuration available where needed.
Main Types
PreferenceinprefValidationConfiginprefStandardConfiginprefIndiffConfiginindifferenceBudgetConstraintinmarshallianOptimConfiginmarshallian
Typical Use Cases
- check whether a utility specification behaves like a rational consumer preference
- compute marginal utility and marginal rates of substitution at a bundle
- trace indifference curves for visual analysis
- solve for Marshallian demand under prices and income