J. Command Line Interface

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