Ps-i 2.4 - Tcl/Tk interface

General description

This chapter documents Tcl/Tk commands specific to Ps-i 2.4.

Agentclass-related commands

num_agentclasses: No arguments. Returns the number of agentclasses currently registered with the model.
agentclass_name: One argument: integer. Returns the name of agentclass specified by the first argument.
find_agentclass: One argument: string. Returns index of the agentclass, which name is specified by the first argument.

Attribute-related commands

num_attributes: No arguments. Returns the number of attributes currently registered with the model.
attribute_name: One argument: integer. Returns the name of the attribute specified by the first argument.
find_attribute: One argument: string. Returns the index of the attribute, which name is specified by the first argument.

Routine-related commands

num_routines: No arguments. Returns total number of routines registered with the model.
routine_name: One argument: integer. Returns the name of the routine specified by the first argument.
routine_comment: One argument: integer. Returns the comment associated to the routine specified by the first argument.
routine_type: One argument: integer. Returns the type of the routine specified by the first argument.
get_routine_code: One argument: integer. Returns string representation of expression assigned to the routine. Note that when clauses are converted into equivalent "A?B:C" representations.
find_routine: One argument: string. Returns the index of the routine which name is specified by the first argument.

Field-related commands

num_fields

No arguments. Returns the total number of fields registered with the model

field_name

One argument: integer. Returns the name of the field specified by the first argument.

find_field

One argument: string. Returns the index of the field, which name is specified by the first argument.

field_x_dim

One argument: field number(integer). Returns the width of the field given by the first argument.

field_y_dim

One argument: field number(integer). Returns the height of the field given by the first argument.

apply_effect

This command has three argument: the name of the field to apply to (string), an expression that defines the area of effect (string) and a list of attributes to change.

Example:

apply_effect "landscape" "(agent_x>10) and (rand<1000)" {
	"immutable"  "false"
	"inactive"  "false"
	"influence"  "1"
	"cache" "repertoire(5,set(5,4,13,11,0,1) union random_subset(1, set(3,15) ))"
	-1 "basic"
	}

The above command will affect every tenth agent with X coordinate exceeding 10 in the field called "landscape". The operation performed on each agent will consist of setting immutable and inactive attributes to false, adjust influence to 1, set cache to the result of evaluation of the expression specified in the command and change its agentclass to "basic".

View related commands

num_views: No arguments. Returns the total number of views (displays) registered with the model.
view_name: One argument: integer. Returns the name of the view specified by the first argument.
find_view: One argument: string. Returns the index of the view, which name is specified by the first argument.

Statistics-related commands

set_filename: One argument: string. Specify new file for logging statistics.
num_stats: No arguments. Returns the total number of statistic fields registered with the model.
stat_name: One argument: integer. Returns the name of the statistic specified by the first argument.
stat_type: One argument: integer. Returns the type of the statistic specified by the first argument.
find_stat: One argument: string. Returns the index of the statistics, which the name is specified by the first argument.
num_values: One argument: integer. Specifies the number of values computed by statistic given by the first argument.
get_value: Two arguments: integer, integer. Returns the value, which number is specified by the second argument, of statistic specified by the first argument.
get_value_name: Two arguments: integer, integer. Returns the name of the value, which number is specified by the second argument, of statistic specified by the first argument.

Model execution commands

load_file: One argument: string. Attempts to load specified file into the model. Action taken depends on extension: when .snp file is loaded as snapshot, when .mdl file is loaded as model description, when .scp file is loaded as script.
step: No arguments. Advance one time step. This involves following evolution rules, saving statistics and increasing time variable by 1.
save_state_to_file: One argument: string. Saves current state of the program to the file specified by the first argument.
parse_string: One argument: string. Evaluates the first argument as if it was appended to the last loaded model description file (i.e. without reset of internal state of the program)
model_time: No arguments. Return the current number of the timestep in the model.

Miscellaneous

call_rand: No arguments. Returns a random number produced by a standard C random number generator
add_entropy: Two arguments: a number and another number that specifies how many bits of the first number to use. This commands adds requested number of bits to ps-i entropy pool.
num_keys: No arguments. Returns total number of keys in Ps-i internal registry
get_key: One argument: integer. Returns the string value of key with this number.
get_string: One argument: string. Returns the value correspond to key given by the argument. If no key has been defined returns empty string.
set_string: Two arguments: key (string) and value (also string). Sets the key given by the first argument to the value given by the second value. If key has been assigned a value previously it is discarded.