Named Values

Named values are model-level objects that can be referenced in formulas throughout the model. There are two types: Calculations and Parameters.

Calculation

A Calculation represents a named formula-based value that can be referenced throughout the model.

Key features:

Defined by a Formula
Data type inferred from the formula
Can depend on other calculations, parameters, or table fields
Added using ModelBuilder.add_calculation()

Attributes:

named_value_id: Unique identifier for the calculation
formula: The formula defining the calculation
depends_on_decision: Whether it depends on decision variables
model_level: Whether it’s a model-level value
required_by_output: Whether it’s required in the output
tracking_group: Optional group for change tracking

Examples:

from daitum_model.formula import CONST, SUM, IF

# Simple constant calculation
model.add_calculation("tax_rate", CONST(0.15))

# Calculation using table data
model.add_calculation(
    "total_revenue",
    SUM(products["price"] * products["quantity"])
)

# Calculation using other named values
model.add_parameter("threshold", DataType.DECIMAL, 1000.0)
model.add_calculation(
    "is_high_value",
    IF(
        SUM(products["total_value"]) > model["threshold"],
        True,
        False
    )
)

class Calculation(id, formula, model_level=False, model=None)[source]

Bases: Buildable, Operand

A calculation is one of the three basic objects that make up a V3 Model. It consists of a name, data_type, and a formula.

id

The id or ID of the calculation.

Type:: str

formula

The formula defining the calculation.

Type:: model_generator.structures.Formula

depends_on_decision

Indicates if the calculation depends on a decision.

Type:: bool

model_level

Indicates if the calculation is at the model level.

Type:: bool

required_by_output

Indicates if the calculation is required by the output.

Type:: bool

__init__(id, formula, model_level=False, model=None)[source]

Parameters:

id (str) – Unique identifier for this calculation. Must be a valid Python-style identifier.
formula (Formula) – The formula that defines the calculated value.
model_level (bool) – If True, the calculation is model-level; otherwise scenario-level.
model (ModelBuilder | None) – The ModelBuilder this calculation belongs to. Can be set later via ModelBuilder.add_calculation.

property id: str: The unique identifier for this calculation.

property tracking_group: str | None: The tracking group identifier, or None if change tracking is not enabled.

property tracking_id: str: The ID of the corresponding tracking calculation, or an empty string if not tracked.

set_tracking_group(group)[source]

Sets the tracking group for this calculation. Returns self.

Return type:: Calculation

set_depends_on_decision(depends_on_decision)[source]

Sets whether this calculation depends on a decision variable.

Return type:: Calculation

set_required_by_output(required_by_output)[source]

Sets whether this calculation is required by the output.

Return type:: Calculation

to_string()[source]

Return type:: str

to_data_type()[source]

Return type:: BaseDataType

add_validator(validator)[source]

Attach a validator to this named value.

Each named value can only have one validator per severity level. Attempting to add another validator with the same severity will raise a ValueError.

Parameters:: validator (Validator) – The validator instance to attach.
Raises:: ValueError – If a validator with the same severity has already been added to this field.
Return type:: None

get_validation_values(severity=None)[source]

Retrieve the validation values associated with this named value’s validators.

Parameters:

severity (Severity | None) – If provided, returns only the validation values for that severity level. If None, returns validation values for all attached validators.

Return type:

list[ValidationValuesContainer] | ValidationValuesContainer | None

Returns:

A list of ValidationValuesContainer if severity is None and validators exist.
A single ValidationValuesContainer if a validator matching severity is found.
None if no validators are attached, or if no validator matches the given severity.

get_combined_message_value()[source]

Returns a single calculated named value that combines all per-severity message values into one array, ordered from highest to lowest severity (CRITICAL → ERROR → WARNING → INFO). Blank messages are excluded from the array.

The resulting value is registered on the model with the ID {id}__message__combined and cached so subsequent calls return the same value without rebuilding it.

Returns:: The combined message calculated value, or None if this named value has no validators.
Return type:: Calculation | Parameter | None
Raises:: NotImplementedError – If this named value has not yet been attached to a model.

Parameter

A Parameter represents a named static value that can be referenced in formulas.

Key features:

Holds a static value
Explicitly typed with a DataType
Can be changed without modifying formulas
Added using ModelBuilder.add_parameter()

Attributes:

named_value_id: Unique identifier for the parameter
data_type: The data type of the parameter
value: The static value
model_level: Whether it’s a model-level value
required_by_output: Whether it’s required in the output
tracking_group: Optional group for change tracking

Examples:

from daitum_model import DataType

# Add numeric parameters
model.add_parameter("discount_rate", DataType.DECIMAL, 0.1)
model.add_parameter("max_orders", DataType.INTEGER, 100)

# Add string parameter
model.add_parameter("default_status", DataType.STRING, "Pending")

# Add boolean parameter
model.add_parameter("enable_discounts", DataType.BOOLEAN, True)

# Use parameters in calculations
model.add_calculation(
    "discounted_price",
    products["price"] * (1 - model["discount_rate"])
)

class Parameter(id, data_type, value=None, model_level=False)[source]

Bases: Buildable, Operand

A parameter is one of the three basic objects that make up a model. It is the simplest of these three objects and consists only of a data_type, a id, as well as optional import_format and model_level.

id

The id or ID of the parameter.

Type:: str

data_type

The type of data that the parameter takes.

Type:: DataType

model_level

Indicates if the parameter is at the model level.

Type:: bool

__init__(id, data_type, value=None, model_level=False)[source]

Parameters:

id (str) – Unique identifier for this parameter. Must be a valid Python-style identifier.
data_type (BaseDataType) – The data type of the parameter value.
value (Any | None) – The initial value of the parameter, or None if not yet set.
model_level (bool) – If True, the parameter is model-level; otherwise scenario-level.

property id: str: The unique identifier for this parameter.

property tracking_group: str | None: The tracking group identifier, or None if change tracking is not enabled.

property tracking_id: str: The ID of the corresponding tracking parameter, or an empty string if not tracked.

set_tracking_group(group)[source]

Sets the tracking group for this parameter. Returns self.

Return type:: Parameter

set_model(model)[source]

Attach this parameter to a ModelBuilder. Returns self.

Return type:: Parameter

set_import_format(import_format)[source]

Sets the import format string for this parameter.

Return type:: Parameter

to_string()[source]

Return type:: str

to_data_type()[source]

Return type:: BaseDataType

to_named_value_dict()[source]

Converts the Parameter object to a dictionary representation for JSON serialisation.

Returns:: A dictionary representation of the Parameter object.
Return type:: dict[str, Any]

add_validator(validator)[source]

Attach a validator to this named value.

Each named value can only have one validator per severity level. Attempting to add another validator with the same severity will raise a ValueError.

Parameters:: validator (Validator) – The validator instance to attach.
Raises:: ValueError – If a validator with the same severity has already been added to this field.
Return type:: None

get_validation_values(severity=None)[source]

Retrieve the validation values associated with this named value’s validators.

Parameters:

severity (Severity | None) – If provided, returns only the validation values for that severity level. If None, returns validation values for all attached validators.

Return type:

list[ValidationValuesContainer] | ValidationValuesContainer | None

Returns:

A list of ValidationValuesContainer if severity is None and validators exist.
A single ValidationValuesContainer if a validator matching severity is found.
None if no validators are attached, or if no validator matches the given severity.

get_combined_message_value()[source]

Returns a single calculated named value that combines all per-severity message values into one array, ordered from highest to lowest severity (CRITICAL → ERROR → WARNING → INFO). Blank messages are excluded from the array.

The resulting value is registered on the model with the ID {id}__message__combined and cached so subsequent calls return the same value without rebuilding it.

Returns:: The combined message calculated value, or None if this named value has no validators.
Return type:: Calculation | Parameter | None
Raises:: NotImplementedError – If this named value has not yet been attached to a model.

Using Named Values

Accessing Named Values:

# Access a calculation or parameter
tax_rate = model["tax_rate"]
discount = model["discount_rate"]

# Use in formulas
products.add_calculated_field(
    "price_with_tax",
    DataType.DECIMAL,
    formula=products["price"] * (1 + tax_rate)
)

Model-Level vs Scenario-Level:

# Model-level calculation (default)
model.add_calculation(
    "global_tax_rate",
    CONST(0.15),
    model_level=True
)

# Scenario-level parameter
model.add_parameter(
    "scenario_discount",
    DataType.DECIMAL,
    0.1,
    model_level=False
)

Dependencies and Optimization:

# Calculation that depends on decision variables
model.add_calculation(
    "total_cost",
    SUM(products["quantity"] * products["unit_cost"]),
    depends_on_decision=True
)