Parsing

The parser module provides tools for converting mathematical expressions to callable functions.

skagent.parser.bound_from_text(bound)

Returns a control bound declared in a document as something skagent.block.normalize_bound() accepts.

A document cannot hold a callable, so a bound given as an expression is compiled into one whose parameter names are the expression’s free variables. Other declarations are passed through unchanged.

skagent.parser.control_constructor(loader, node)

A PyYAML constructor building a skagent.block.Control.

skagent.parser.math_text_to_lambda(text)

Returns a function represented by the given mathematical text.

skagent.parser.skagent_loader()

A PyYAML loader that supports tags for scikit-agent, such as random variables and model tags.

skagent.parser.validate_block(document, name=None)

Refuse a block document whose keys are not a block’s keys.

A block declares its parts at one level – shocks, dynamics, reward – and names its variables one level below. A part indented one step too deep is still valid YAML: it becomes a VARIABLE of the part above it, so the block silently loses that whole section and gains a symbol nobody declared. Nothing downstream can tell that apart from a block that never had the section, which is why it is caught here rather than left to fail later.

A document holding blocks is read as a recursive block, and its sub-blocks are validated too.

Parameters:

• document (Mapping) – One block, as a document holds it. A model document – a calibration beside a list of blocks – is not a block; validate its blocks.

• name (str, optional) – What to call the block when something is wrong with it. Defaults to the document’s own name.

Raises:

ValueError – If a key of the document is not one the block has a place for, or if one of the block’s own keys is used as a variable inside another.

Core Parser Functions

skagent.parser.math_text_to_lambda(text)

Returns a function represented by the given mathematical text.

skagent.parser.skagent_loader()

A PyYAML loader that supports tags for scikit-agent, such as random variables and model tags.

skagent.parser.validate_block(document, name=None)

Refuse a block document whose keys are not a block’s keys.

A block declares its parts at one level – shocks, dynamics, reward – and names its variables one level below. A part indented one step too deep is still valid YAML: it becomes a VARIABLE of the part above it, so the block silently loses that whole section and gains a symbol nobody declared. Nothing downstream can tell that apart from a block that never had the section, which is why it is caught here rather than left to fail later.

A document holding blocks is read as a recursive block, and its sub-blocks are validated too.

Parameters:

• document (Mapping) – One block, as a document holds it. A model document – a calibration beside a list of blocks – is not a block; validate its blocks.

• name (str, optional) – What to call the block when something is wrong with it. Defaults to the document’s own name.

Raises:

ValueError – If a key of the document is not one the block has a place for, or if one of the block’s own keys is used as a variable inside another.

!Control is built by a constructor rather than represented by a token class, so a parsed control is a skagent.block.Control and every consumer of a Python-authored block reads it unchanged.

skagent.parser.control_constructor(loader, node)

A PyYAML constructor building a skagent.block.Control.

Parser Classes

class skagent.parser.Expression(text)

Bases: object

func()

Rules

The rule module builds on the parser to extract dependencies and formulas from model rules.

Universal rule processing module for scikit-agent models.

This module provides utilities for working with “rules” - the right-hand side expressions in structural statements that define model dynamics, controls, and rewards.

A rule can be: - A callable (function, lambda) - A Control object - A Distribution or tuple with distribution parameters - A string expression, or the Rule that a block compiles one into - A constant value

Key functions: - format_rule: Get printable string version of a rule - extract_dependencies: Get variables that a rule depends on

skagent.rule.extract_dependencies(rule)

Extract variable dependencies from a model rule.

Parameters:

rule (various) – Can be Control, Distribution, Rule, callable, tuple, or string

Returns:

List of dependency variable names

Return type:

list

skagent.rule.extract_formula(rule)

Extract formula as string from a rule.

Parameters:

rule (various) – The rule to extract formula from

Returns:

The formula as string

Return type:

str

skagent.rule.format_rule(var, rule)

Get a printable (string) version of a rule.

Parameters:

• var (str) – The variable name (LHS of structural statement)

• rule (callable, Control, str, or any) – The rule to format (RHS of structural statement)

Returns:

A human-readable string representation of the rule

Return type:

str

skagent.rule.math_text_to_free_variable_names(txt)

Extract free variable names from mathematical text using SymPy.

Parameters:

txt (str) – Mathematical expression as string

Returns:

List of free variable names

Return type:

list

Examples

>>> math_text_to_free_variable_names("10 * x + y **2 - z")
['x', 'y', 'z']

Example Usage

Parsing Mathematical Expressions

import inspect

from skagent.parser import math_text_to_lambda

# Convert a string expression to a callable function
reward_func = math_text_to_lambda("c**(1-rho)/(1-rho)")

# The positional argument order follows the expression's free symbols.
# Check it before calling the function positionally:
inspect.signature(reward_func)  # (c, rho)

reward = reward_func(1.5, 2.0)

Warning

Variable names that collide with built-in SymPy objects are parsed as those objects rather than as free variables. For example, gamma is parsed as the gamma function, so math_text_to_lambda("c**(1-gamma)/(1-gamma)") raises a TypeError. Prefer names like rho or CRRA for curvature parameters.