Utils

This section contains the API documentation for utility functions and helpers.

Parser Utilities

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

class skagent.parser.ControlToken(args)

Represents a parsed Control variable.

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.

Core Parser Functions

skagent.parser.math_text_to_lambda(text)

Returns a function represented by the given mathematical text.

Parser Classes

class skagent.parser.ControlToken(args)

Bases: object

Represents a parsed Control variable.

class skagent.parser.Expression(text)

Bases: object

func()

General Utilities

The utils module contains general-purpose utility functions.

skagent.utils.apply_fun_to_vals(fun, vals)

Applies a function to the arguments defined in vals. This is equivalent to fun(**vals), except that vals may contain keys that are not named arguments of fun.

Parameters:

  • fun (callable)

  • vals (dict)

skagent.utils.compute_gradients_for_tensors(tensors_dict, wrt, create_graph=False)

Compute gradients for a dictionary of tensors with respect to variables.

This function computes gradients using PyTorch’s autograd. It is used by the gradient methods on BellmanPeriod (grad_reward_function, grad_transition_function, and grad_pre_state_function).

For batched inputs, this computes the diagonal of the Jacobian: for each batch element i, we compute ∂target[i]/∂var[i]. The implementation uses grad(target.sum(), var), which yields the correct diagonal whenever target[i] depends only on var[i] (sample-independence). This assumption holds when each batch element is computed independently, which is the case for element-wise reward and transition functions in this library.

For scalar inputs, .sum() is a no-op, so the same code path handles both cases without branching.

Parameters:

  • tensors_dict (dict[str, Tensor]) – Dictionary mapping symbol names to tensors to compute gradients for.

  • wrt (dict[str, Tensor]) – Dictionary of variables to compute gradients with respect to. Keys are variable names, values are tensors with requires_grad=True.

  • create_graph (bool) – If True, the graph of the derivative is constructed, allowing higher-order derivatives and end-to-end training. Default: False.

Returns:

Nested dictionary of gradients for each tensor symbol and variable: {tensor_sym: {var_name: gradient}}. Gradient is None if and only if the variable does not require gradients or no computational graph path exists from the variable to the target tensor. A zero tensor is returned when the dependency exists but evaluates to zero. Callers should treat None as structural independence, not as a zero gradient.

Return type:

dict[str, dict[str, Tensor | None]]

skagent.utils.compute_parameter_difference(params1, params2)

Compute the L2 norm of the difference between two parameter vectors.

skagent.utils.create_vectorized_function_wrapper_with_mapping(lambda_func, param_to_column)

Create a vectorized wrapper that automatically maps lambda parameters to correct tensor columns based on a parameter-to-column mapping.

Parameters:

  • lambda_func – Original lambda function

  • param_to_column – A mapping from parameter names to columns of a tensor

skagent.utils.extract_parameters(network)

Extract all parameters from a PyTorch network into a flat tensor.

skagent.utils.reconcile(vec_a, vec_b)

Returns a new vector with the values of vec_b but with the object type and shape of vec_a.

Example Usage

Parsing Mathematical Expressions

from skagent.parser import math_text_to_lambda

# Convert string expression to callable function
utility_func = math_text_to_lambda("c**(1-gamma)/(1-gamma)")

# Use the function
gamma = 2.0
c = 1.5
utility = utility_func(c, gamma)

Working with Grids

import skagent as ska

# Create a grid configuration
config = {
    "wealth": {"min": 0.0, "max": 10.0, "count": 50},
    "income": {"min": 0.5, "max": 2.0, "count": 20},
}

# Create grid
grid = ska.Grid.from_config(config)

# Access grid points
wealth_points = grid["wealth"]
income_points = grid["income"]

# Convert to dictionary
grid_dict = grid.to_dict()

This page is under construction. Content will be added as the API develops.