psychsim.pwl package

Submodules

psychsim.pwl.keys module

psychsim.pwl.keys.actionFieldKey(feature)

psychsim.pwl.keys.actionKey(name, future=False)

psychsim.pwl.keys.belief2believer(key)

psychsim.pwl.keys.belief2key(key)

psychsim.pwl.keys.beliefKey(name, key)

psychsim.pwl.keys.binaryKey(subj, obj, relation)

psychsim.pwl.keys.escapeKey(key)

Returns:filename-ready version of the key

psychsim.pwl.keys.isActionKey(key)

psychsim.pwl.keys.isBeliefKey(key)

psychsim.pwl.keys.isBinaryKey(key)

psychsim.pwl.keys.isFuture(key)

psychsim.pwl.keys.isLikesKey(key)

psychsim.pwl.keys.isModelKey(key)

psychsim.pwl.keys.isRewardKey(key)

psychsim.pwl.keys.isSpecialKey(key)

Returns:True iff the given key is a state key and its feature is a reserved name (e.g., for a turn, model, reward, etc)

psychsim.pwl.keys.isStateKey(key)

Returns:C{True} iff this key refers to a state feature Return type:bool

psychsim.pwl.keys.isTurnKey(key)

psychsim.pwl.keys.key2relation(key)

psychsim.pwl.keys.likesKey(subj, obj)

psychsim.pwl.keys.makeFuture(key)

Returns:a reference to the given state features’ projected future value Return type:str

psychsim.pwl.keys.makePresent(key)

Returns:a reference to the given state features’ current value Return type:str

psychsim.pwl.keys.model2name(key)

psychsim.pwl.keys.modelKey(name, future=False)

psychsim.pwl.keys.rewardKey(name, future=False)

psychsim.pwl.keys.state2agent(key)

Returns:the agent name from the given key Return type:str

psychsim.pwl.keys.state2feature(key)

Returns:the feature string from the given key Return type:str

psychsim.pwl.keys.state2tuple(key)

Returns:the separated agent name and feature from the given key Return type:(str,str)

psychsim.pwl.keys.stateKey(name, feature, future=False)

Parameters:future (bool) – if C{True}, then this refers to the projected value of this feature (default is C{False}) Returns:a key representation of a given entity’s state feature Return type:str

psychsim.pwl.keys.turn2name(key)

psychsim.pwl.keys.turnKey(name)

psychsim.pwl.matrix module

class psychsim.pwl.matrix.KeyedMatrix(arg=None)

Bases: object

Keeps rows in order by key

changeTense(future=True, keyList=None)

Transforms matrix so that each row refers to only future keys :param keyList: If present, only references to these keys (within each row) are made future

desymbolize(table, debug=False)

getKeysIn()

Returns:a set of keys which affect the result of multiplying by this matrix

getKeysOut()

Returns:a set of keys which are changed as a result of multiplying by this matrix

items()

keys()

makeFuture(keyList=None)

Transforms matrix so that each row refers to only future keys :param keyList: If present, only references to these keys (within each row) are made future

makePresent(keyList=None)

multiply_distribution(other)

multiply_matrix(other)

multiply_vector(other)

scale(table)

update(other)

psychsim.pwl.matrix.addFeatureMatrix(key, otherKey, pct=1)

Returns:a dynamics matrix adding a percentage of another feature value to the given feature value (default percentage is 100%) Return type:L{KeyedMatrix}

psychsim.pwl.matrix.approachMatrix(key, weight, limit, limitKey='')

Parameters:

• weight (float) – the percentage by which you want the feature to approach the limit
• limit (float) – the value you want the feature to approach
• limitKey (str) – the feature whose value to approach (default is CONSTANT)

Returns:

a dynamics matrix modifying the given keyed value by approaching the given limit by the given weighted percentage of distance

Return type:

L{KeyedMatrix}

psychsim.pwl.matrix.dynamicsMatrix(key, vector)

Returns:a dynamics matrix setting the given key to be equal to the given weighted sum Return type:L{KeyedMatrix}

psychsim.pwl.matrix.incrementMatrix(key, delta)

Parameters:delta (float) – the constant value to add to the state feature Returns:a dynamics matrix incrementing the given keyed value by the constant delta Return type:L{KeyedMatrix}

psychsim.pwl.matrix.noChangeMatrix(key)

Returns:a dynamics matrix indicating no change to the given keyed value Return type:L{KeyedMatrix}

psychsim.pwl.matrix.nullMatrix(key)

Returns:a fake dynamics matrix that doesn’t change time Return type:L{KeyedMatrix}

psychsim.pwl.matrix.scaleMatrix(key, weight)

Returns:a dynamics matrix modifying the given keyed value by scaling it by the given weight Return type:L{KeyedMatrix}

psychsim.pwl.matrix.setFalseMatrix(key)

psychsim.pwl.matrix.setToConstantMatrix(key, value)

Returns:a dynamics matrix setting the given keyed value to the constant value Return type:L{KeyedMatrix}

psychsim.pwl.matrix.setToFeatureMatrix(key, otherKey, pct=1, shift=0)

Returns:a dynamics matrix setting the given keyed value to a percentage of another keyed value plus a constant shift (default is 100% with shift of 0) Return type:L{KeyedMatrix}

psychsim.pwl.matrix.setTrueMatrix(key)

psychsim.pwl.plane module

class psychsim.pwl.plane.KeyedPlane(planes, threshold=None, comparison=None)

Bases: object

String indexable hyperplane class :ivar vector: the weights for the hyperplane :type vector: L{KeyedVector} :ivar threshold: the threshold for the hyperplane :type threshold: float :ivar comparison: if 1, value must be above hyperplane; if -1, below; if 0, equal (default is 1) :type comparison: int

COMPARISON_MAP = ['==', '>', '<']

DEFAULT_COMPARISON = 1

DEFAULT_THRESHOLD = 0.0

changeTense(future=True, keyList=None)

compare(other, value)

Identifies any potential conflicts between two hyperplanes :return: C{None} if no conflict was detected, C{True} if the tests are redundant, C{False} if the tests are conflicting :warning: correct, but not complete

desymbolize(table, debug=False)

desymbolizeThreshold(threshold, table)

evaluate(vector, p_index=None)

Tests whether the given vector passes or fails this test. Also accepts a numeric value, in lieu of doing a dot product. :param p_index: evaluate against only the given plane (not all of them in case this is a con/disjunctive branch) :type p_index: int :rtype: bool :warning: If multiple planes are present, an AND over their results is assumed

keys()

makeFuture(keyList=None)

Transforms this plane to refer to only future versions of its columns :param keyList: If present, only references to these keys are made future

makePresent(keyList=None)

Transforms this plane to refer to only current versions of its columns :param keyList: If present, only references to these keys are made present

minimize()

parse(element)

possible(variables)

scale(table)

psychsim.pwl.plane.andRow(trueKeys=[], falseKeys=[])

Parameters:

• trueKeys (str[]) – list of keys which must be C{True} (default is empty list)
• falseKeys (str[]) – list of keys which must be C{False} (default is empty list)

Returns:

a plane testing whether all boolean keyed values are set as desired

Return type:

L{KeyedPlane}

psychsim.pwl.plane.differenceRow(key1, key2, threshold)

Returns:a plane testing whether the difference between the first and second keyed values exceeds the given threshold Return type:L{KeyedPlane}

psychsim.pwl.plane.equalFeatureRow(key1, key2)

Returns:a plane testing whether the values of the two given features are equal Return type:L{KeyedPlane}

psychsim.pwl.plane.equalRow(key, value)

Returns:a plane testing whether the given keyed value (or sum of keyed values) equals the given target value Return type:L{KeyedPlane}

psychsim.pwl.plane.falseRow(key)

Returns:a plane testing whether a boolean keyed value is False Return type:L{KeyedPlane}

psychsim.pwl.plane.greaterThanRow(key1, key2)

Returns:a plane testing whether the first keyed value is greater than the second Return type:L{KeyedPlane}

psychsim.pwl.plane.thresholdRow(key, threshold)

Returns:a plane testing whether the given keyed value exceeds the given threshold Return type:L{KeyedPlane}

psychsim.pwl.plane.trueRow(key)

Returns:a plane testing whether a boolean keyed value is True Return type:L{KeyedPlane}

psychsim.pwl.state module

class psychsim.pwl.state.VectorDistributionSet(start=None)

Bases: object

Represents a distribution over independent state vectors, i.e., independent L{VectorDistribution}s

add_distribution(dist)

Parameters:dist (VectorDistribution) – The sub-distribution to add to this state Warning:Keys in new distribution must not already exist in current distribution Returns:the index into the newly added distribution

clear()

collapse(substates, preserve_certainty=True)

Collapses (in place) the given substates into a single joint L{VectorDistribution}

copySubset(ignore=None, include=None)

copy_subset(ignore=None, include=None)

copy_value(old_key, new_key)

Modifies the state so that the distribution over the new key’s values is identical to that of the old key

deleteKeys(toDelete)

Removes multiple columns at once

delete_value(key, value)

Removes the given value for the given key from the state and then renormalizes :param value: value (or set of values) to be removed

diff(other)

Returns:a dictionary of differences between me and the given state

domain(key)

findUncertainty(substates=None)

Parameters:substates – Consider only the given substates as candidates Returns:a substate containing an uncertain distribution if one exists; otherwise, None Return type:int

is_minimal()

Returns:False iff any non-singleton distributions are non-singleton for all variables in that distribution”

items()

join(key, value, substate=None)

Modifies the distribution over vectors to have the given value for the given key :param key: the key to the column to modify :type key: str :param value: either a single value to apply to all vectors, or else a L{Distribution} over possible values :substate: name of substate vector distribution to join with, ignored if the key already exists in this state. By default, find a new substate

keys()

make_certain()

marginal(key)

merge(substates)

Returns:the substate into which they’ve all been merged

multiply_matrix(other)

multiply_tree(other, probability=1, select=False)

multiply_vector(other)

normalize()

probability(vector=None)

Returns:the probability of the given world according to this state distribution. If no world is given, then return the probability of the overall state

prune(threshold)

prune_probability(threshold: float) → float

prune_size(k: int = 1) → float

replace(substitution, key=None)

Replaces column values, either across all columns, or only for the specified column

rollback(debug=False)

Removes any current state values and makes any future state values the current ones :param debug: if True, then run some checks on the values

select(maximize=False, incremental=False)

Reduce distribution to a single element, sampled according to the given distribution :param incremental: if C{True}, then select each key value in series (rather than picking out a joint vector all at once, default is C{False}) :return: the probability of the selection made

setitem(key, value)

simpleRollback(futures)

split(key)

Returns:partitions this distribution into subsets corresponding to possible values for the given key Return type:dict(str,VectorDistributionSet)

subDistribution(key)

subdistribution(key)

Returns:the minimal joint distribution containing this key

substate(obj, ignoreCertain=False)

Returns:the substate referred to by all of the keys in the given object

uncertain()

Returns:C{True} iff this distribution has any uncertainty about the vector Return type:bool

update(other, keySet, scale=1)

vector()

Returns:if this distribution contains only a single vector, return that vector; otherwise, throw exception Return type:KeyedVector

verifyIntegrity(sumToOne=False)

worlds()

Returns:iterator through all possible joint vectors (i.e., possible worlds) and their probabilities Return type:KeyedVector,float

psychsim.pwl.tree module

class psychsim.pwl.tree.KeyedTree(leaf=None, plane=None, children=None)

Bases: object

Decision tree node using symbolic PWL structures @ivar leaf: C{True} iff this node is a leaf @type leaf: bool @ivar children: table of children of this node @type children: dict @ivar branch: the hyperplane branch at this node (if applicable) @type branch: L{KeyedPlane}

ceil(key, hi)

Modify this tree to make sure the new computed value never goes higher than the given ceiling @warning: may introduce redundant checks

changeTense(future=True, keyList=None)

Transforms this vector to refer to only future versions of its columns @param keyList: If present, only references to these keys are made future

collapseProbabilistic()

Utility method that combines any consecutive probabilistic branches at this node into a single distribution

compose(other, leafOp=None, planeOp=None)

Compose two trees into a single tree :param other: the other tree to be composed with :type other: L{KeyedTree} :param leafOp: the binary operator to apply to leaves of each tree to generate a new leaf :param planeOp: the binary operator to apply to the plane :rtype: L{KeyedTree}

desymbolize(table, debug=False)

@return: a new tree with any symbolic references replaced with numeric values according to the table of element lists @rtype: L{KeyedTree}

expectation()

@return: a new tree representing an expectation over any probabilistic branches

floor(key, lo)

Modify this tree to make sure the new computed value never goes lower than the given floor @warning: may introduce redundant checks

getKeysIn()

@return: a set of all keys that affect the output of this PWL function

getKeysOut()

@return: a set of all keys that are affected by this PWL function

getLeaf()

graft(root)

Grafts a tree at the current node @warning: clobbers anything currently at (or rooted at) this node

isLeaf()

isProbabilistic()

@return: C{True} if there is a probabilistic branch at this node @rtype: bool

keys()

leaves()

Warning:May return a list containing duplicates

makeBranch(plane: psychsim.pwl.plane.KeyedPlane, children: Dict[Any, Any])

makeFuture(keyList=None)

makeLeaf(leaf: Any)

makePresent(keyList=None)

makeProbabilistic(distribution: psychsim.probability.Distribution)

map(leafOp=None, planeOp=None, distOp=None)

Generates a new tree applying a function to all planes and leaves @param leafOp: functional transformation of leaf nodes @type leafOp: lambda XS{->}X @param planeOp: functional transformation of hyperplanes @type planeOp: lambda XS{->}X @param distOp: functional transformation of probabilistic branches @type distOp: lambda L{Distribution}S{->}X @rtype: L{KeyedTree}

max(other)

minimizePlanes()

Modifies tree in place so that there are no constant factors in branch weights

parse(element)

prune(path=[], variables={})

Removes redundant branches :warning: correct, but not necessarily complete

replace(old, new)

@return: a new tree with the given substitution applied to all leaf nodes

sample(mostlikely=False, vector=None)

Parameters:

• mostlikely (bool) – if True, then only the most likely branches are chosen at each probabilistic branch
• vector (KeyedVector) – if provided, return the leaf node corresponding to the given possible world

Returns:

a tree sampled from all of the probabilistic branches

sampleLeaf(vector, mostlikely=False)

Parameters:mostlikely (bool) – if True, then only the most likely branches are chosen at each probabilistic branch Returns:a leaf node sampled from the distribution over leaf nodes for the given vector

scale(table)

psychsim.pwl.tree.collapseDynamics(tree, effects, variables={})

psychsim.pwl.tree.makeTree(table, normalize=True)

psychsim.pwl.vector module

class psychsim.pwl.vector.KeyedVector(arg={})

Bases: collections.abc.MutableMapping

Class for a compact, string-indexable vector :cvar epsilon: the margin used for equality of vectors (as well as for testing hyperplanes in L{KeyedPlane}) :type epsilon: float :ivar _string: the C{str} representation of this vector :type _string: bool

changeTense(future=True, keyList=None)

copy_value(old_key, new_key)

Modifies the state so that the distribution over the new key’s values is identical to that of the old key

desymbolize(table, debug=False)

diff(other)

distance(vector)

Returns:the distance between the given vector and myself Return type:float

epsilon = 1e-08

filter(ignore)

Returns:a copy of me applying the given lambda expression to the keys (if a list is provided, then any keys in that list are dropped out) Return type:KeyedVector

hyperString()

Returns:a string representation of this vector treating it as a weighted sum

makeFuture(keyList=None)

Transforms this vector to refer to only future versions of its columns :param keyList: If present, only references to these keys are made future

makePresent(keyList=None)

nearestNeighbor(vectors)

Returns:the vector in the given set that is closest to me Return type:KeyedVector

normalize()

Multiplies all of the weights so that the smallest weight is 1 and the relative values are preserved :return: the multiplier used

prune()

rollback(future=None)

sortedString()

class psychsim.pwl.vector.VectorDistribution(args=None, rationality=None)

Bases: psychsim.probability.Distribution

A class representing a L{Distribution} over L{KeyedVector} instances

copy_value(old_key, new_key)

Modifies the state so that the distribution over the new key’s values is identical to that of the old key

deleteKey(key)

Removes the specified column from all vectors in this distribution :type key: str

delete_column(key)

Removes the specified column from all vectors in this distribution :type key: str

domain(key=None)

Returns:the sample space of this probability distribution Return type:generator

element_to_str(element)

group_by_certainty(suppress_certain=False)

hasColumn(key)

Returns:C{True} iff the given key appears in all of the vectors of this distribution Return type:bool

join(key, value)

Modifies the distribution over vectors to have the given value for the given key :param key: the key to the column to modify :type key: str :param value: either a single value to apply to all vectors, or else a L{Distribution} over possible values

keys()

Returns:The keys of the vectors in the domain (assumed to be uniform),

NOT the keys of the domain itself

marginal(key)

merge(other, inPlace=False)

Merge two distributions (the passed-in distribution takes precedence over this one in case of conflict) :type other: VectorDistribution :param inPlace: if C{True}, modify this distribution directly; otherwise, return a new distribution (default is C{False}) :type inPlace: bool :return: the merged distribution :rtype: VectorDistribution

prune_probability(probThreshold, true=None)

Removes any elements in the distribution whose probability is strictly less than the given threshold :param normalize: Normalize distribution after pruning if True (default is False) :return: the probability mass remaining after pruning (and before any normalization)

replace(substitution, key=None)

Replaces column values, either across all columns, or only for the specified column

rollback(future=None)

select(maximize=False, incremental=False)

Parameters:incremental – if C{True}, then select each key value in series (rather than picking out a joint vector all at once, default is C{False})

Module contents

Class and function definitions for PieceWise Linear (PWL) representations