Skip to content

J. Command Line Interface

Roberto Ulloa edited this page Aug 21, 2016 · 15 revisions

The command line offers the same functionality as the Batch Mode, but is meant to be used with servers and without a graphical user interface. It might also be preferred by individuals who prefer the keyboard over the mouse. After the introductory learning phase with the GUI, the command line is the fastest way to interact with the Cultural Simulator. It is also more flexible than Batch Mode, as creating configuration files is not necessary. Instead, the main input is a csv file, a results folder), or event files (and the language is parsed from the parameters in the command line).

In order to use the command line, you open a terminal and go to the directory on your computer that contains the culsim.jar, a Java executable. You can execute this file directly with java -jar culsim.jar $ARGS, but you will also find two executables, culsim.bat for Windows and culsim.sh for Unix/Linux (and iOS - note that this is not tested). If no arguments ($ARGS) are provided, then the Graphical User Interface will appear. As with Batch Mode, the are two general tests that can be performed with the Command Line:

1. Testing convergence states of simulations (from a csv file):

Here is an example of how to test the convergence state of different simulation configurations in Unix/Linux (for Windows, use culsim.bat):

./culsim.sh -id sample_experiment -ef sample.csv 

The -id parameter is optional; it sets a name for the results folder and final results file (See H. Output Files) that are stored in the current directory; the directory where the command is executed. If no -id is provided, results will be used by default.

The -ef parameter indicates the csv file that contains the configurations of the simulations that are going to be executed. The file sample.csv is provided in the same folder as an example (the two rows are equivalent except for the institutional influence). Here is a description of all columns (parameters) of the simulation, corresponding to the Initial Parameters (with the exception of REPETITIONS, which indicate the number of times the configuration will be repeated):

CSV Column Parameter
REPETIONS Repetitions
MODEL Model
RANDOM_INITIALIZATION Random initialization
ITERATIONS Iterations
SPEED Speed
BUFFER_SIZE Buffer size
ROWS Rows
COLS Columns
RADIUS Radius
FEATURES Features
TRAITS Traits
MUTATION Mutation
SELECTION_ERROR Selection error
INST_INFLUENCE Institutional influence
AGENT_LOYALTY Agent loyalty
DEMOCRACY Democracy
PROPAGANDA Propaganda

2. Testing the effect of an event in simulation sets (from Results Folder):

There are two ways of inputting events in the batch mode. One is configuring the event(s) directly in the command line. The other requires the use of the interface, first, to define and save the event(s) into a file and, then, to use the file to execute the event.

A. Configuring events directly in the command line

Here is an example of a (composed) event in the simulation, set in Unix/Linux (for Windows, use culsim.bat):

./culsim.bat -r -id sample_event_experiment -rd ./sample_experiment/ -r 1  -evs G@U,0.1 I@N,0.5,0.5,0.2 P@iterations,1000 

The -id parameter is optional; it sets a name for the results folder and final results file (See H. Output Files), so that, instead of the current directory, they are stored inside the results folder (see -rd parameter). If no -id is provided, results will be used by default.

The -rd parameter indicates the results directory that will be used to test the (simple or composed) event. In this case we are assuming that you executed the previous step with the example, and that you keep the same ID, i.e. sample_experiment.

The -r is optional; it indicates the number of times the (simple or composed) event will be executed, for each simulation state (repetitions). Repetitions make more sense when the events depend on a probabilistic distribution, e.g. a uniform distribution of the event, or there is an element of probability, e.g. when the (non-probabilistic) Neumann distribution has a center that is selected randomly, by using -1 in the rows and/or columns.

The -evs parameter indicates the events which will be executed in the provided simulation sets. A special syntax (instead of events files) has been provided to define events. It basically follows the format Event_type@Distribution for events that affect institutions or agents, and P@parameter,value for parameter change event. The first letter(s) before the @ indicates the event type according to the following table:

Id Event
A Apostasy
D Institutional destruction
RP Content removal (Partial)
RF Content removal (Full)
CP Conversion (Partial)
CF Conversion (Full)
S Settlement
I Immigration
G Decimation
P Parameter Change Event

The part after the @ defines a distribution for events that affect agents or institutions. The table below explains the meaning of each parameter for each distribution (the first parameter identifies the distribution, and the rest its parameters):

Parameters Distribution
U,p (U)niform distribution with probability p
N,row,col,max,sd (N)ormal distribution centered at (row,col) with maximum value of max and standard deviation sd. The center can be chosen randomly by using -1 in the rows and/or columns.
E,row,col,max,p Normal (E)stimated distribution centered at (row,col) with maximum value of max and proportion p. The center can be chosen randomly by using -1 in the rows and/or columns.
W,row,col,r Neumann (not ne(W) man) distribution center at (row,col) with radius r. The center can be chosen randomly by using -1 in the rows and/or columns.
R,row1,col1,row2,col2 (R)ectangular distribution with the initial position at (row1,col1), and final position at (row2,col2)

For the Parameter Change Event, instead of a distribution, the part after the @ defines the parameter that will be affected, and its value. For example P@iterations,1000 will change the number of iterations to 1000. The following table shows the list of arguments that can be used instead of iterations.

Argument Parameter
iterations Iterations
speed Speed
mutation Mutation
selection Selection error
influence Institutional influence
loyalty Agent loyalty
democracy Democracy
propaganda Propaganda

B. Using pre configured file event

Alternatively, you can create event files with the interface (see D. Events), and use -evs_file to specify the path of the file. An equivalent to the previous command would be:

./culsim.bat -r -id sample_event_experiment -rd ./sample_experiment/ -r 1  -evs_file path/to/event_file