tyche.language

This module contains the classes for representing aleatoric description logic (ADL) sentences, and the maths for their evaluation.

exception tyche.language.TycheLanguageException(message)

An exception type that is thrown when errors occur in the construction or use of the ADL language constructs.

Parameters:

message (str) – A description of the error.

class tyche.language.RoleDist

A probability distribution of related contexts.

is_empty()

Returns whether no individuals (including None) have been added to this role. If None was explicitly added, then this will return False.

Return type:

bool

clear()

Removes all individuals from this distribution.

contains(individual)

Returns whether this role distribution contains the given individual.

Parameters:

individual (Optional[TycheContext]) –

contexts()

Yields all the contexts within this role, including the None-individual if it is present.

calculate_expectation(node, given)

Evaluates an expectation over this role. This evaluation contains an implicit given that the role has at least one related individual. If the role contains no non-null entries, then this will evaluate to vacuously True.

Parameters:

• node (ADLNode) –

• given (ADLNode) –

Return type:

float

reverse_expectation_learning_params(node, given, likelihood=1)

Calculates the influence and learning rate of each related individual in this role for the truth of an expectation with the given parameters. The likelihood gives the chance that the observation was true (i.e., a likelihood of 0 represents that the observation of this expectation was false).

Returns a tuple of each related context that could have been selected, its likelihood, and its influence.

Parameters:

• node (ADLNode) –

• given (ADLNode) –

• likelihood (float) –

Return type:

list[tuple[‘TycheContext’, float, float]]

calculate_exists()

Evaluates the likelihood that this role has at least one related individual. The null individual is considered to represent “no relation”.

to_str(*, detail_lvl=1, indent_lvl=0)

Returns a text representation of the contents of this role distribution.

Parameters:

• detail_lvl (int) –

• indent_lvl (int) –

class tyche.language.ExclusiveRoleDist(entries=None)

Bases: RoleDist

A probability distribution of contexts for a role, where either zero or one related contexts are related when the role is observed. The zero in this case refers to the possibility of selecting the None-individual. However, exactly one individual is always selected if you include the None-individual. The items in the probability distribution use weights to represent their relative likelihood of being selected.

Parameters:

entries (Union[None, list[Union[ForwardRef('TycheContext'), Tuple[ForwardRef('TycheContext'), float]]], dict['TycheContext', float]]) –

is_empty()

Returns whether no individuals (including None) have been added to this role. If None was explicitly added, then this will return False.

Return type:

bool

property total_weight

The sum of the weights of all entries in this role distribution.

clear()

Removes all individuals from this distribution.

contains(individual)

Returns whether this role distribution contains the given individual.

Parameters:

individual (Optional[TycheContext]) –

add(individual, weight=1)

Add an individual to this distribution with the given weighting. The weightings of individuals are relative to one another. If an individual already exists in the distribution, then its weighting will be _replaced_.

If no weight is supplied, then the default of 1 will be used.

Parameters:

• individual (Optional[TycheContext]) –

• weight (float) –

add_combining_weights(individual, weight)

Add an individual to this distribution. If the individual already exists in this role, then the given weight will be added to their existing weight. Otherwise, the given weight will be used as the weight of the individual.

Parameters:

• individual (Optional[TycheContext]) –

• weight (float) –

remove(individual)

Removes the given individual from this distribution.

Parameters:

individual (Optional[TycheContext]) –

contexts()

Yields all the contexts within this role, including the None-individual if it is present.

apply_bayes_rule(observation, likelihood=1, learning_rate=1)

Applies Bayes’ rule to update the probabilities of the individuals mapped within this role based upon an uncertain observation. This cannot learn anything about the None individual. Returns an updated role distribution.

The likelihood works by applying bayes rule to the event that the observation occurred or was incorrectly observed ((event with likelihood) OR (NOT event with 1 - likelihood)). Therefore, a likelihood of 0 represents that the observation was observed to be false (this is equivalent to observing NOT observation). See: https://stats.stackexchange.com/questions/345200/applying-bayess-theorem-when-evidence-is-uncertain

The learning_rate works by acting as a weight for the result of Bayes’ rule, and the original weight. A learning_rate of 1 represents to just use the result of Bayes’ rule. A learning_rate of 0 represents that the weight of each individual in the role should remain unchanged.

Parameters:

• observation (ADLNode) –

• likelihood (float) –

• learning_rate (float) –

Return type:

ExclusiveRoleDist

calculate_expectation(node, given)

Evaluates an expectation over this role. This evaluation contains an implicit given that the role has at least one related individual. If the role contains no non-null entries, then this will evaluate to vacuously True.

Parameters:

• node (ADLNode) –

• given (ADLNode) –

Return type:

float

reverse_expectation_learning_params(node, given, likelihood=1)

Calculates the influence and learning rate of each related individual in this role for the truth of an expectation with the given parameters. The likelihood gives the chance that the observation was true (i.e., a likelihood of 0 represents that the observation of this expectation was false).

Returns a tuple of each related context that could have been selected, its likelihood, and its influence.

Parameters:

• node (ADLNode) –

• given (ADLNode) –

• likelihood (float) –

Return type:

list[tuple[‘TycheContext’, float, float]]

calculate_exists()

Evaluates the likelihood that this role has at least one related individual. The null individual is considered to represent “no relation”.

sample(rng)

Selects a random individual from this role based upon their weights.

Parameters:

rng (Generator) –

Return type:

Optional[TycheContext]

to_str(*, detail_lvl=1, indent_lvl=0)

Returns a text representation of the contents of this role distribution.

Parameters:

• detail_lvl (int) –

• indent_lvl (int) –

class tyche.language.IndependentRoleDist(entries=None)

Bases: RoleDist

A probability distribution of contexts for a role, where each relation to the contexts is independent. That is, zero, one, or many contexts may be related when the role is observed. Each relation has an independent probability of existing when sampled. IndependentRoleDist cannot contain the None-individual.

Parameters:

entries (Union[None, list[Union[ForwardRef('TycheContext'), Tuple[ForwardRef('TycheContext'), float]]], dict['TycheContext', float]]) –

is_empty()

Returns whether no individuals (including None) have been added to this role. If None was explicitly added, then this will return False.

Return type:

bool

clear()

Removes all individuals from this distribution.

contains(individual)

Returns whether this role distribution contains the given individual.

Parameters:

individual (Optional[TycheContext]) –

add(individual, prob=1)

Add an individual to this distribution with the given probability. The probability must fall within the range [0, 1].

Parameters:

• individual (TycheContext) –

• prob (float) –

remove(individual)

Removes the given individual from this distribution.

Parameters:

individual (TycheContext) –

contexts()

Yields all the contexts within this role, including the None-individual if it is present.

calculate_expectation(node, given)

Evaluates an expectation over this role. This evaluation contains an implicit given that the role has at least one related individual. If the role contains no non-null entries, then this will evaluate to vacuously True.

Parameters:

• node (ADLNode) –

• given (ADLNode) –

Return type:

float

reverse_expectation_learning_params(node, given, likelihood=1)

Calculates the influence and learning rate of each related individual in this role for the truth of an expectation with the given parameters. The likelihood gives the chance that the observation was true (i.e., a likelihood of 0 represents that the observation of this expectation was false).

Returns a tuple of each related context that could have been selected, its likelihood, and its influence.

Parameters:

• node (ADLNode) –

• given (ADLNode) –

• likelihood (float) –

Return type:

list[tuple[‘TycheContext’, float, float]]

calculate_exists()

Evaluates the likelihood that this role has at least one related individual. The null individual is considered to represent “no relation”.

sample(rng)

Selects a random set of related individuals based upon their probabilities.

Parameters:

rng (Generator) –

Return type:

list[‘TycheContext’]

to_str(*, detail_lvl=1, indent_lvl=0)

Returns a text representation of the contents of this role distribution.

Parameters:

• detail_lvl (int) –

• indent_lvl (int) –

class tyche.language.TycheContext

Provides context for relating variables in formulas (e.g. a, b, c, etc…) to their related objects. Each individual may supply their own context for their variables and roles.

eval(concept)

Evaluates the given concept to a probability of it being true if sampled within this context.

Parameters:

concept (CompatibleWithADLNode) –

Return type:

float

eval_role(role)

Evaluates the given role to a distribution of possible other contexts if it were sampled within this context.

Parameters:

role (CompatibleWithRole) –

Return type:

RoleDist

observe(observation, likelihood=1, learning_rate=1)

Attempts to update the beliefs of this individual based upon an observation of the given concept.

The optional likelihood parameter provides a degree of certainty about the observation. By default, the observation is assumed to be reliable.

Parameters:

• observation (ADLNode) –

• likelihood (float) –

• learning_rate (float) –

get_concept(symbol)

Gets the probability of the atom with the given symbol being true, without modification by the context.

Parameters:

symbol (str) –

Return type:

float

get_role(symbol)

Gets the role distribution of the role with the given symbol, without modification by the context.

Parameters:

symbol (str) –

Return type:

RoleDist

get_concept_reference(symbol)

Gets a mutable reference to the probability of the atom with the given symbol being true. This reference can be used to get and set the value of the atom.

Parameters:

symbol (str) –

Return type:

BakedSymbolReference[float]

get_role_reference(symbol)

Gets a mutable reference to the role distribution of the role with the given symbol. This reference can be used to get and set the value of the role.

Parameters:

symbol (str) –

Return type:

BakedSymbolReference[RoleDist]

to_str(*, detail_lvl=1, indent_lvl=0)

A version of str() that allows additional formatting options to be specified. Allows specifying the number of levels of detail to include, and the indentation to use while formatting.

Parameters:

• detail_lvl (int) –

• indent_lvl (int) –

class tyche.language.EmptyContext

Bases: TycheContext

Provides an empty context for evaluating constant expressions.

eval(concept)

Evaluates the given concept to a probability of it being true if sampled within this context.

Parameters:

concept (ADLNode) –

Return type:

float

eval_role(role)

Evaluates the given role to a distribution of possible other contexts if it were sampled within this context.

Parameters:

role (Role) –

Return type:

RoleDist

get_concept(symbol)

Gets the probability of the atom with the given symbol being true, without modification by the context.

Parameters:

symbol (str) –

Return type:

float

get_role(symbol)

Gets the role distribution of the role with the given symbol, without modification by the context.

Parameters:

symbol (str) –

Return type:

RoleDist

get_concept_reference(symbol)

Gets a mutable reference to the probability of the atom with the given symbol being true. This reference can be used to get and set the value of the atom.

Parameters:

symbol (str) –

Return type:

float

get_role_reference(symbol)

Gets a mutable reference to the role distribution of the role with the given symbol. This reference can be used to get and set the value of the role.

Parameters:

symbol (str) –

Return type:

RoleDist

to_str(*, detail_lvl=1, indent_lvl=0)

A version of str() that allows additional formatting options to be specified. Allows specifying the number of levels of detail to include, and the indentation to use while formatting.

Parameters:

• detail_lvl (int) –

• indent_lvl (int) –

class tyche.language.ADLNode

The base class of all nodes in aleatoric description logic formulas.

static cast(node)

This provides the canonicalization of several supported ADL representations into ADLNode objects. For example, strings are automatically considered to represent concepts, and as such they may be converted into concept nodes automatically by this function.

Parameters:

node (CompatibleWithADLNode) –

Return type:

ADLNode

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[‘ADLNode’]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

direct_eval(context)

Disclaimer: This should _NOT_ be called to evaluate nodes using your model, as the TycheContext objects should be given the control over the method of evaluation. Therefore, TycheContext#eval should usually be used instead.

Evaluates the probability of this node evaluating to true when sampled using the values of concepts and roles from the given context and related contexts.

Parameters:

context (TycheContext) –

Return type:

float

normal_form()

Returns the tree normal form of the formula, where atoms are ordered alphabetically.

Return type:

ADLNode

is_equivalent(node)

Returns true if this node is provably equivalent to the given node. Delegates to normal_form function. Two nodes have the same normal form if and only if they have the same evaluation function

Parameters:

node (ADLNode) –

Return type:

bool

is_weaker(node)

Returns true if the probability of this node is provably necessarily less than or equal to the probability of the given node.

Parameters:

node (ADLNode) –

Return type:

bool

is_stronger(node)

Returns true if the probability of this node is provably necessarily greater than or equal to the probability of the given node.

Parameters:

node (ADLNode) –

Return type:

bool

when(condition)

Returns a formula that represents (condition ? self : Always). This is equivalent to the formula self -> condition. You can use a.when(b).otherwise(c) to represent (b ? a : c).

Parameters:

condition (CompatibleWithADLNode) –

Return type:

ConditionalWithoutElse

complement()

Produces a new node that represents the complement (negation) of this node. i.e., this performs a logical NOT operation to this node.

Return type:

ADLNode

class tyche.language.Atom(symbol, *, special_symbol=False)

Bases: ADLNode

Represents indivisible nodes such as concepts and constants such as always or never.

Parameters:

• symbol (str) –

• special_symbol (bool) –

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[tyche.language.ADLNode]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

static check_symbol(symbol, *, symbol_name='symbol', symbol_type_name='Atom', context=None)

Checks a string contains only alphanumeric characters or underscore. Raises an error if the symbol is an invalid atom symbol.

Parameters:

• symbol (str) –

• symbol_type_name (str) –

• context (Optional[str]) –

normal_form()

Returns the tree normal form of the formula, where atoms are ordered alphabetically.

is_equivalent(node)

Returns true if this node is provably equivalent to the given node. Delegates to normal_form function. Two nodes have the same normal form if and only if they have the same evaluation function

Parameters:

node (ADLNode) –

Return type:

bool

is_weaker(node)

Returns true if the probability of this node is provably necessarily less than or equal to the probability of the given node.

class tyche.language.Concept(symbol)

Bases: Atom

Represents indivisible nodes such as concepts and constants such as always or never.

Parameters:

symbol (str) –

direct_eval(context)

Disclaimer: This should _NOT_ be called to evaluate nodes using your model, as the TycheContext objects should be given the control over the method of evaluation. Therefore, TycheContext#eval should usually be used instead.

Evaluates the probability of this node evaluating to true when sampled using the values of concepts and roles from the given context and related contexts.

Parameters:

context (TycheContext) –

Return type:

float

eval_reference(context)

Evaluates to a mutable reference to the value of this concept.

Parameters:

context (TycheContext) –

Return type:

BakedSymbolReference[float]

class tyche.language.Constant(symbol, probability)

Bases: Atom

A constant named aleatoric probability.

Parameters:

• symbol (str) –

• probability (float) –

direct_eval(context)

Disclaimer: This should _NOT_ be called to evaluate nodes using your model, as the TycheContext objects should be given the control over the method of evaluation. Therefore, TycheContext#eval should usually be used instead.

Evaluates the probability of this node evaluating to true when sampled using the values of concepts and roles from the given context and related contexts.

Parameters:

context (TycheContext) –

Return type:

float

class tyche.language.Role(symbol, *, special_symbol=False)

Represents the relationships between contexts.

Parameters:

• symbol (str) –

• special_symbol (bool) –

eval_reference(context)

Evaluates to a mutable reference to the value of this role.

Parameters:

context (TycheContext) –

Return type:

BakedSymbolReference[RoleDist]

class tyche.language.ConstantRole(symbol, value)

Bases: Role

Represents a relationship that is constant.

Parameters:

• symbol (str) –

• value (RoleDist) –

eval_reference(context)

Evaluates to a mutable reference to the value of this role.

Parameters:

context (TycheContext) –

Return type:

BakedSymbolReference[RoleDist]

class tyche.language.ReferenceBackedRole(value_ref)

Bases: Role

Represents a relationship that’s value is taken from a reference.

Parameters:

value_ref (SymbolReference[RoleDist]) –

eval_reference(context)

Evaluates to a mutable reference to the value of this role.

Parameters:

context (TycheContext) –

Return type:

BakedSymbolReference[RoleDist]

class tyche.language.Conditional(condition, if_yes, if_no)

Bases: ADLNode

Represents an aleatoric ternary construct (if-then-else).

Parameters:

• condition (CompatibleWithADLNode) –

• if_yes (CompatibleWithADLNode) –

• if_no (CompatibleWithADLNode) –

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[tyche.language.ADLNode]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

is_known_noop()

Returns whether this conditional does nothing. i.e., (A ? ALWAYS : NEVER).

is_known_complement()

Returns whether this conditional is a complement operation. i.e., NOT A.

is_known_conjunction()

Returns whether this conditional is a conjunction. i.e., A AND B.

is_known_disjunction()

Returns whether this conditional is a disjunction. i.e., A OR B.

to_str(*, allow_no_brackets=False)

Converts this node to a string, and potentially omits the enclosing brackets if specifically allowed.

Parameters:

allow_no_brackets (bool) –

direct_eval(context)

Disclaimer: This should _NOT_ be called to evaluate nodes using your model, as the TycheContext objects should be given the control over the method of evaluation. Therefore, TycheContext#eval should usually be used instead.

Evaluates the probability of this node evaluating to true when sampled using the values of concepts and roles from the given context and related contexts.

Parameters:

context (TycheContext) –

normal_form()

Returns the tree normal form of the conditional, by recursively calling normal for on sub elements.

is_weaker(node)

Returns true if the probability of this node is provably necessarily less than or equal to the probability of the given node.

class tyche.language.ConditionalWithoutElse(condition, if_yes)

Bases: Conditional

Represents an aleatoric ternary construct of the form (condition ? if_yes : Always).

Parameters:

• condition (CompatibleWithADLNode) –

• if_yes (CompatibleWithADLNode) –

class tyche.language.Given(node, given)

Bases: ADLNode

Represents a node that should only be evaluated after the given evaluates to true. Due to this, the evaluation of the Given must be handled by the context. Therefore, these should be avoided generally, and only used when they are required.

Parameters:

• node (CompatibleWithADLNode) –

• given (CompatibleWithADLNode) –

static maybe_unpack(node, given=None)

If the node is a Given, then this unpacks the Given into its constituent node and the given node. If a given is explicitly provided whilst the node is also a Given, the returned given will be the conjunction of both. If the node is not a Given, then the provided node and given will be returned. If the given is not provided, then ALWAYS will be returned for the given. Returns a tuple of (node, given).

Parameters:

• node (CompatibleWithADLNode) –

• given (Optional[CompatibleWithADLNode]) –

Return type:

tuple[tyche.language.ADLNode, tyche.language.ADLNode]

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[tyche.language.ADLNode]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

direct_eval(context)

Disclaimer: This should _NOT_ be called to evaluate nodes using your model, as the TycheContext objects should be given the control over the method of evaluation. Therefore, TycheContext#eval should usually be used instead.

Evaluates the probability of this node evaluating to true when sampled using the values of concepts and roles from the given context and related contexts.

Parameters:

context (TycheContext) –

normal_form()

Returns the tree normal form of the formula, where atoms are ordered alphabetically.

is_weaker(node)

Returns true if the probability of this node is provably necessarily less than or equal to the probability of the given node.

class tyche.language.Expectation(role, eval_node, given_node=None)

Bases: ADLNode

Represents the aleatoric expectation construct, ‘The expectation that node is true for an individual selected randomly from the given role, given that the individual evaluates given to true’. If given is not given, then it defaults to always.

Parameters:

• role (CompatibleWithRole) –

• eval_node (CompatibleWithADLNode) –

• given_node (Optional[CompatibleWithADLNode]) –

get_content_node()

Returns a node that contains the contents of this expectation including both the evaluation node, and the given node if one was provided on construction.

Return type:

ADLNode

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[tyche.language.ADLNode]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

static evaluate_role_under_role(outer_role, inner_role)

Evaluates the expected role over a given set of roles. The chance of the contexts in the returned role represents the chance that the context is selected from an inner_role selected from outer_role.

Parameters:

• outer_role (ExclusiveRoleDist) –

• inner_role (Role) –

Return type:

ExclusiveRoleDist

direct_eval(context)

Evaluates the node for all members of the role mapping from the given context to other contexts. This evaluation contains an implicit given that the role is non-None. If the role only contains None, then this will evaluate to vacuously True.

Parameters:

context (TycheContext) –

class tyche.language.Exists(role)

Bases: ADLNode

Represents the expectation about whether a value for a role exists. i.e. The probability that the value of a role is non-None.

Parameters:

role (CompatibleWithRole) –

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[tyche.language.ADLNode]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

direct_eval(context)

Evaluates the likelihood that the given role has a non-None value.

Parameters:

context (TycheContext) –

class tyche.language.LeastFixedPoint(role, node)

Bases: ADLNode

Disclaimer: This class is not yet functional. It is a work in progress.

class for representing the aleatoric fixed point construct in the language. This is equivalent to the marginal expectation operator, (a|b). See: https://peteroupc.github.io/bernoulli.html

Parameters:

• role (CompatibleWithRole) –

• node (CompatibleWithADLNode) –

get_child_nodes_in_eval_context()

Returns an ordered list of the child nodes of this node that would be evaluated in the same context as this node is evaluated. Nodes that are evaluated in related contexts should not be returned here.

Return type:

list[tyche.language.ADLNode]

copy_with_new_child_node_from_eval_context(index, node)

Returns a copy of this node with the child node at the given index in the list returned by get_children_in_eval_context replaced with the given node.

Parameters:

• index (int) –

• node (ADLNode) –

direct_eval(context)

Complex one, needs iteration or equation solving.

Parameters:

context (TycheContext) –

normal_form()

Returns the tree normal form of the conditional, by recursively calling normal for on sub elements.

is_equivalent(node)

Returns true if this node is provably equivalent to the given node. Delegates to normal_form function. Two nodes have the same normal form if and only if they have the same evaluation function

is_weaker(node)

Returns true if the probability of this node is provably necessarily less than or equal to the probability of the given node.

static is_linear(variable, node)

class method to test whether variable is linear in node