Utilities & Notebook Helpers

Provides some utilities widely used by other modules

utils.sequence(iterable)

Converts iterable to sequence, if it is not already one.

utils.remove_all(item, seq)

Return a copy of seq (or string) with all occurrences of item removed.

utils.unique(seq)

Remove duplicate elements from seq. Assumes hashable elements.

utils.count(seq)

Count the number of items in sequence that are interpreted as true.

utils.multimap(items)

Given (key, val) pairs, return {key: [val, ….], …}.

utils.multimap_items(mmap)

Yield all (key, val) pairs stored in the multimap.

utils.product(numbers)

Return the product of the numbers, e.g. product([2, 3, 10]) == 60

utils.first(iterable, default=None)

Return the first element of an iterable; or default.

utils.is_in(elt, seq)

Similar to (elt in seq), but compares with ‘is’, not ‘==’.

utils.mode(data)

Return the most common data item. If there are ties, return any one of them.

utils.power_set([1,2,3]) --> (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

utils.extend(s, var, val)

Copy dict s and extend it by setting var to val; return copy.

utils.flatten(seqs)

Flatten a sequence of sequences into a single flat list.

utils.identity(x)

utils.argmin_random_tie(seq, key=<function <lambda>>)

Return a minimum element of seq; break ties at random.

utils.argmax_random_tie(seq, key=<function <lambda>>)

Return an element with highest fn(seq[i]) score; break ties at random.

utils.shuffled(iterable)

Randomly shuffle a copy of iterable.

utils.histogram(values, mode=0, bin_function=None)

Return a list of (value, count) pairs, summarizing the input values. Sorted by increasing value, or if mode=1, by decreasing count. If bin_function is given, map it over values first.

utils.dot_product(x, y)

Return the sum of the element-wise product of vectors x and y.

utils.element_wise_product(x, y)

Return vector as an element-wise product of vectors x and y.

utils.matrix_multiplication(x, *y)

Return a matrix as a matrix-multiplication of x and arbitrary number of matrices *y.

utils.vector_add(a, b)

Component-wise addition of two vectors.

utils.scalar_vector_product(x, y)

Return vector as a product of a scalar and a vector

utils.probability(p: float) → bool

Return true with probability p.

utils.weighted_sample_with_replacement(n, seq, weights)

Pick n samples from seq at random, with replacement, with the probability of each element in proportion to its corresponding weight.

utils.weighted_sampler(seq, weights)

Return a random-sample function that picks from seq weighted by weights.

utils.weighted_choice(choices)

A weighted version of random.choice

utils.rounder(numbers, d=4)

Round a single number, or sequence of numbers, to d decimal places.

utils.num_or_str(x: str) → int | float | str

The argument is a string; convert to a number if possible, or strip it.

utils.euclidean_distance(x, y) → float

Return the Euclidean (L2) distance between vectors x and y.

utils.manhattan_distance(x, y) → float

Return the Manhattan (L1) distance between vectors x and y.

utils.hamming_distance(x, y) → int

Return the number of positions at which vectors x and y differ.

utils.cross_entropy_loss(x, y) → float

Return the mean binary cross-entropy loss between targets x and predictions y.

utils.mean_squared_error_loss(x, y) → float

Return the mean squared error loss between vectors x and y.

utils.rms_error(x, y) → float

Return the root-mean-square error between vectors x and y.

utils.ms_error(x, y) → float

Return the mean of the squared differences between vectors x and y.

utils.mean_error(x, y) → float

Return the mean of the absolute differences between vectors x and y.

utils.mean_boolean_error(x, y) → float

Return the fraction of positions at which vectors x and y differ.

utils.normalize(dist)

Multiply each number by a constant such that the sum is 1.0

utils.random_weights(min_value: float, max_value: float, num_weights: int) → list

Return a list of num_weights random floats drawn uniformly from [min_value, max_value].

utils.sigmoid(x)

Return activation value of x with sigmoid function.

utils.sigmoid_derivative(value)

Return the derivative of the sigmoid, given its already-computed output value.

utils.elu(x: float, alpha: float = 0.01) → float

Return the Exponential Linear Unit activation of x.

utils.elu_derivative(value: float, alpha: float = 0.01) → float

Return the derivative of the ELU activation, given its output value.

utils.tanh(x)

Return the hyperbolic tangent activation of x.

utils.tanh_derivative(value)

Return the derivative of tanh, given its already-computed output value.

utils.leaky_relu(x: float, alpha: float = 0.01) → float

Return the Leaky ReLU activation of x (slope alpha for negative inputs).

utils.leaky_relu_derivative(value: float, alpha: float = 0.01) → float

Return the derivative of the Leaky ReLU activation, given its output value.

utils.relu(x: float) → float

Return the Rectified Linear Unit activation of x, i.e. max(0, x).

utils.relu_derivative(value: float) → int

Return the derivative of the ReLU activation, given its output value.

utils.step(x: float) → int

Return activation value of x with sign function

utils.gaussian(mean: float, st_dev: float, x: float) → float

Given the mean and standard deviation of a distribution, it returns the probability of x.

utils.linear_kernel(x, y=None)

Return the linear kernel (dot product) between x and y; defaults y to x.

utils.polynomial_kernel(x, y=None, degree=2.0)

Return the polynomial kernel (1 + x.y)**degree between x and y; defaults y to x.

utils.rbf_kernel(x, y=None, gamma=None)

Radial-basis function kernel (aka squared-exponential kernel).

utils.turn_heading(heading, inc, headings=[(1, 0), (0, 1), (-1, 0), (0, -1)])

Return the heading reached by turning inc steps around the list of headings.

utils.turn_right(heading)

Return the heading obtained by turning right (clockwise) from heading.

utils.turn_left(heading)

Return the heading obtained by turning left (counter-clockwise) from heading.

utils.distance(a, b)

The distance between two (x, y) points.

utils.distance_squared(a, b)

The square of the distance between two (x, y) points.

class utils.injection(**kwds)

Bases: object

Dependency injection of temporary values for global functions/classes/etc. E.g., with injection(DataBase=MockDataBase): …

utils.memoize(fn, slot=None, maxsize=32)

Memoize fn: make it remember the computed value for any argument list. If slot is specified, store result in that slot of first argument. If slot is false, use lru_cache for caching the values.

utils.name(obj)

Try to find some reasonable name for the object.

utils.isnumber(x)

Is x a number?

utils.issequence(x)

Is x a sequence?

utils.print_table(table, header=None, sep='   ', numfmt='{}')

Print a list of lists as a table, so that columns line up nicely. header, if specified, will be printed as the first row. numfmt is the format for all numbers; you might want e.g. ‘{:.2f}’. (If you want different formats in different columns, don’t use print_table.) sep is the separator between columns.

utils.open_data(name, mode='r')

Open and return the file named name from the aima-data directory.

utils.failure_test(algorithm, tests)

Grades the given algorithm based on how many tests it passes. Most algorithms have arbitrary output on correct execution, which is difficult to check for correctness. On the other hand, a lot of algorithms output something particular on fail (for example, False, or None). tests is a list with each element in the form: (values, failure_output).

class utils.Expr(op, *args)

Bases: object

A mathematical expression with an operator and 0 or more arguments. op is a str like ‘+’ or ‘sin’; args are Expressions. Expr(‘x’) or Symbol(‘x’) creates a symbol (a nullary Expr). Expr(‘-’, x) creates a unary; Expr(‘+’, x, 1) creates a binary.

utils.Symbol(name)

A Symbol is just an Expr with no args.

utils.symbols(names)

Return a tuple of Symbols; names is a comma/whitespace delimited str.

utils.subexpressions(x)

Yield the subexpressions of an Expression (including x itself).

utils.arity(expression)

The number of sub-expressions in this expression.

class utils.PartialExpr(op, lhs)

Bases: object

Given ‘P |’==>’| Q, first form PartialExpr(‘==>’, P), then combine with Q.

utils.expr(x)

Shortcut to create an Expression. x is a str in which: - identifiers are automatically defined as Symbols. - ==> is treated as an infix |’==>’|, as are <== and <=>. If x is already an Expression, it is returned unchanged. Example:

>>> expr('P & Q ==> Q')
((P & Q) ==> Q)

utils.expr_handle_infix_ops(x)

Given a str, return a new str with ==> replaced by |’==>’|, etc.

>>> expr_handle_infix_ops('P ==> Q')
"P |'==>'| Q"

class utils.defaultkeydict

Bases: defaultdict

Like defaultdict, but the default_factory is a function of the key. >>> d = defaultkeydict(len); d[‘four’] 4

class utils.hashabledict

Bases: dict

Allows hashing by representing a dictionary as tuple of key:value pairs. May cause problems as the hash value may change during runtime.

class utils.PriorityQueue(order='min', f=<function PriorityQueue.<lambda>>)

Bases: object

A Queue in which the minimum (or maximum) element (as determined by f and order) is returned first. If order is ‘min’, the item with minimum f(x) is returned first; if order is ‘max’, then it is the item with maximum f(x). Also supports dict-like lookup.

append(item)

Insert item at its correct position.

extend(items)

Insert each item in items at its correct position.

pop()

Pop and return the item (with min or max f(x) value) depending on the order.

class utils.Bool

Bases: int

Just like bool, except values display as ‘T’ and ‘F’ instead of ‘True’ and ‘False’.

Provides some utilities widely used by other modules

class utils4e.PriorityQueue(order='min', f=<function PriorityQueue.<lambda>>)

Bases: object

A Queue in which the minimum (or maximum) element (as determined by f and order) is returned first. If order is ‘min’, the item with minimum f(x) is returned first; if order is ‘max’, then it is the item with maximum f(x). Also supports dict-like lookup.

append(item)

Insert item at its correct position.

extend(items)

Insert each item in items at its correct position.

pop()

Pop and return the item (with min or max f(x) value) depending on the order.

utils4e.sequence(iterable)

Converts iterable to sequence, if it is not already one.

utils4e.remove_all(item, seq)

Return a copy of seq (or string) with all occurrences of item removed.

utils4e.unique(seq)

Remove duplicate elements from seq. Assumes hashable elements.

utils4e.count(seq)

Count the number of items in sequence that are interpreted as true.

utils4e.multimap(items)

Given (key, val) pairs, return {key: [val, ….], …}.

utils4e.multimap_items(mmap)

Yield all (key, val) pairs stored in the multimap.

utils4e.product(numbers)

Return the product of the numbers, e.g. product([2, 3, 10]) == 60

utils4e.first(iterable, default=None)

Return the first element of an iterable; or default.

utils4e.is_in(elt, seq)

Similar to (elt in seq), but compares with ‘is’, not ‘==’.

utils4e.mode(data)

Return the most common data item. If there are ties, return any one of them.

utils4e.power_set([1,2,3]) --> (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

utils4e.extend(s, var, val)

Copy dict s and extend it by setting var to val; return copy.

utils4e.flatten(seqs)

Flatten a sequence of sequences into a single flat list.

utils4e.identity(x)

utils4e.argmin_random_tie(seq, key=<function <lambda>>)

Return a minimum element of seq; break ties at random.

utils4e.argmax_random_tie(seq, key=<function <lambda>>)

Return an element with highest fn(seq[i]) score; break ties at random.

utils4e.shuffled(iterable)

Randomly shuffle a copy of iterable.

utils4e.histogram(values, mode=0, bin_function=None)

Return a list of (value, count) pairs, summarizing the input values. Sorted by increasing value, or if mode=1, by decreasing count. If bin_function is given, map it over values first.

utils4e.element_wise_product(x, y)

Return the element-wise product of x and y, recursing into nested iterables.

Scalars are multiplied directly; iterables must have matching lengths.

utils4e.vector_add(a, b)

Component-wise addition of two vectors.

utils4e.scalar_vector_product(x, y)

Return vector as a product of a scalar and a vector recursively.

utils4e.map_vector(f, x)

Apply function f to iterable x.

utils4e.probability(p: float) → bool

Return true with probability p.

utils4e.weighted_sample_with_replacement(n, seq, weights)

Pick n samples from seq at random, with replacement, with the probability of each element in proportion to its corresponding weight.

utils4e.weighted_sampler(seq, weights)

Return a random-sample function that picks from seq weighted by weights.

utils4e.weighted_choice(choices)

A weighted version of random.choice

utils4e.rounder(numbers, d=4)

Round a single number, or sequence of numbers, to d decimal places.

utils4e.num_or_str(x: str) → int | float | str

The argument is a string; convert to a number if possible, or strip it.

utils4e.euclidean_distance(x, y) → float

Return the Euclidean (L2) distance between vectors x and y.

utils4e.manhattan_distance(x, y) → float

Return the Manhattan (L1) distance between vectors x and y.

utils4e.hamming_distance(x, y) → int

Return the number of positions at which vectors x and y differ.

utils4e.rms_error(x, y) → float

Return the root-mean-square error between vectors x and y.

utils4e.ms_error(x, y) → float

Return the mean of the squared differences between vectors x and y.

utils4e.mean_error(x, y) → float

Return the mean of the absolute differences between vectors x and y.

utils4e.mean_boolean_error(x, y) → float

Return the fraction of positions at which vectors x and y differ.

utils4e.cross_entropy_loss(x, y) → float

Cross entropy loss function. x and y are 1D iterable objects.

utils4e.mean_squared_error_loss(x, y) → float

Min square loss function. x and y are 1D iterable objects.

utils4e.normalize(dist)

Multiply each number by a constant such that the sum is 1.0

utils4e.random_weights(min_value: float, max_value: float, num_weights: int) → list

Return a list of num_weights random floats drawn uniformly from [min_value, max_value].

utils4e.conv1D(x, k)

1D convolution. x: input vector; K: kernel vector.

utils4e.gaussian_kernel(size=3)

Return a length-size 1D Gaussian kernel centred at the middle (fixed st_dev 0.1).

utils4e.gaussian_kernel_1D(size=3, sigma=0.5)

Return a length-size 1D Gaussian kernel centred at the middle with st_dev sigma.

utils4e.gaussian_kernel_2D(size=3, sigma=0.5)

Return a size x size 2D Gaussian kernel with st_dev sigma, normalized to sum to 1.

utils4e.step(x: float) → int

Return activation value of x with sign function.

utils4e.gaussian(mean: float, st_dev: float, x: float) → float

Given the mean and standard deviation of a distribution, it returns the probability of x.

utils4e.linear_kernel(x, y=None)

Return the linear kernel (dot product) between x and y; defaults y to x.

utils4e.polynomial_kernel(x, y=None, degree=2.0)

Return the polynomial kernel (1 + x.y)**degree between x and y; defaults y to x.

utils4e.rbf_kernel(x, y=None, gamma=None)

Radial-basis function kernel (aka squared-exponential kernel).

utils4e.turn_heading(heading, inc, headings=[(1, 0), (0, 1), (-1, 0), (0, -1)])

Return the heading reached by turning inc steps around the list of headings.

utils4e.turn_right(heading)

Return the heading obtained by turning right (clockwise) from heading.

utils4e.turn_left(heading)

Return the heading obtained by turning left (counter-clockwise) from heading.

utils4e.distance(a, b)

The distance between two (x, y) points.

utils4e.distance_squared(a, b)

The square of the distance between two (x, y) points.

class utils4e.injection(**kwds)

Bases: object

Dependency injection of temporary values for global functions/classes/etc. E.g., with injection(DataBase=MockDataBase): …

utils4e.memoize(fn, slot=None, maxsize=32)

Memoize fn: make it remember the computed value for any argument list. If slot is specified, store result in that slot of first argument. If slot is false, use lru_cache for caching the values.

utils4e.name(obj)

Try to find some reasonable name for the object.

utils4e.isnumber(x)

Is x a number?

utils4e.issequence(x)

Is x a sequence?

utils4e.print_table(table, header=None, sep='   ', numfmt='{}')

Print a list of lists as a table, so that columns line up nicely. header, if specified, will be printed as the first row. numfmt is the format for all numbers; you might want e.g. ‘{:.2f}’. (If you want different formats in different columns, don’t use print_table.) sep is the separator between columns.

utils4e.open_data(name, mode='r')

Open and return the file named name from the aima-data directory.

utils4e.failure_test(algorithm, tests)

Grades the given algorithm based on how many tests it passes. Most algorithms have arbitrary output on correct execution, which is difficult to check for correctness. On the other hand, a lot of algorithms output something particular on fail (for example, False, or None). tests is a list with each element in the form: (values, failure_output).

class utils4e.Expr(op, *args)

Bases: object

A mathematical expression with an operator and 0 or more arguments. op is a str like ‘+’ or ‘sin’; args are Expressions. Expr(‘x’) or Symbol(‘x’) creates a symbol (a nullary Expr). Expr(‘-’, x) creates a unary; Expr(‘+’, x, 1) creates a binary.

utils4e.Symbol(name)

A Symbol is just an Expr with no args.

utils4e.symbols(names)

Return a tuple of Symbols; names is a comma/whitespace delimited str.

utils4e.subexpressions(x)

Yield the subexpressions of an Expression (including x itself).

utils4e.arity(expression)

The number of sub-expressions in this expression.

class utils4e.PartialExpr(op, lhs)

Bases: object

Given ‘P |’==>’| Q, first form PartialExpr(‘==>’, P), then combine with Q.

utils4e.expr(x)

Shortcut to create an Expression. x is a str in which: - identifiers are automatically defined as Symbols. - ==> is treated as an infix |’==>’|, as are <== and <=>. If x is already an Expression, it is returned unchanged. Example:

>>> expr('P & Q ==> Q')
((P & Q) ==> Q)

utils4e.expr_handle_infix_ops(x)

Given a str, return a new str with ==> replaced by |’==>’|, etc.

>>> expr_handle_infix_ops('P ==> Q')
"P |'==>'| Q"

class utils4e.defaultkeydict

Bases: defaultdict

Like defaultdict, but the default_factory is a function of the key. >>> d = defaultkeydict(len); d[‘four’] 4

class utils4e.hashabledict

Bases: dict

Allows hashing by representing a dictionary as tuple of key:value pairs. May cause problems as the hash value may change during runtime.

class utils4e.MCT_Node(parent=None, state=None, U=0, N=0)

Bases: object

Node in the Monte Carlo search tree, keeps track of the children states.

utils4e.ucb(n, C=1.4)

Return the UCB1 score of node n (exploitation plus C-weighted exploration term).

Unvisited nodes (n.N == 0) score infinity so they are selected first; used to guide selection in Monte Carlo tree search.

class utils4e.Bool

Bases: int

Just like bool, except values display as ‘T’ and ‘F’ instead of ‘True’ and ‘False’.