/users/rlr/Courses/ICPSR-03/Handouts/demo1-script.txt
-----------------------------------------------------

# login to your account---see the handout:
#           getting-started.txt 
# for information on how to login, and then bring up an "xterm"
# window into which you can type the commands as shown below.

# The following makes a number of directories (folders) for different demos

make-icpsr-dirs

You can see the names of them with this command to
"list files in current directory, in long format":

ls -l                That is: el es <spaces> dash el

# lets go into the directory for Schelling's "tipping" model 

cd Tipping

# lets run the schelling tipping model:

tipping &

# three GUI widgets
# - control panel: start, next, quit, ...
# - ObserverSwarm: control display frequence; writeHelp ; debug level
# - Parameters: Model parameters that can be changed
#    (These are described in the writeHelp text -- see below.)
#
# You can move all widgets around by
#  - position mouse in the middle part of the top bar
#  - press and hold the left mouse button, and drag
#    to where you want it, then release mouse button

# lets see what the writeHelp does...

<press writeHelp>

# To change the font in one of these "xterm" windows, i.e.,
# the windows where you type commands, do <^mb3>
# which means:
#  - position mouse in the xterm window
#  - hold CTRL key down, and press the right mouse button
#  - while holding mb3 down, scroll down to font to try
# (**The above may not work on some systems...)

# NOTE on using mice in ICPSR lab:
# Normally, linux/unix uses 3-button mice.
# Two-buttom mice have Left (mb1) and right (mb3).
# To use mb2 ("middle"), hold both down at once.

# To create another "x-terminal" window, with more history,
# enter this command in any existing xterm:
#     xterm -sb -sl 5000

# Note on creating simulations: 
# I find it useful to include a writeHelp text in a model right 
# from the start, as much for me as for others!
# ===> Documenting your computer models is crucial for 
# ===> making "computer modeling" into a reproducible science!

# In any case...lets just run with the model parameter with most
# of the default values, *except* lets change to oneStepMode=1.
# To do that, put mouse in the oneStepMode value slot, 
# do a mouse button click to focus on that slot, change the value to 1,
# and then be sure to press <Enter> (the slot will flash red).

# now lets initialize the model:

<press next>

# four more gui widgets should pop up, showing the model's state 
# just after world and agents are created and initialized. 
# - World: agents in their locations, color coded
#          as described in the text from writeHelp
#     One agent will be blue or white--blue is a green
#       agent that wants to move next, white is a red one.
# - various graphs, as described in writeHelp:
#   - Count vs T: 
#   - Pop Avgs vs T (3 of these)
# Actually nothing will be in the graphs for until a few steps run.

# Lets 'probe' the one agent that is blue or white
# i.e., the one that is to move next.

<mb3 on the one that is blue or white>

# A new widget should pop up. This displays the
# internal "state" of the agent you probed. 
# Each agent has
# - ID 
# - x,y location
# - agent type (1 = red/white, 2 = green/blue)
# - threshold
# - sameNborCnt, diffNborCnt, fracSameNbor
# - nborSites
# - world, worldSize
# - agentColor

# Note this agent has a fracSameNbor < its threshold.
# which is why it wants to move!

# (One could probe other agents as well, and even
# mark them by changing their agentColor value--see writeHelp
# output for details on the colors available.)

# let's take some steps.
# each step these things happen:
# - the unhappy agent that was found last step 
#   looks for a place to move -- default is to
#   move to some randomly chosen open spot.
# - it moves, and then re-evaluates its neighborhood,
#   and all of its old and new neighbors also re-evaluate
#   their neighborhoods.
# - a new unhappy agent is found (at random from all agents), 
#   and its color changes:
#       red->white     green->blue
# - the various aggregate statistics are updated, and written
#   to the screen, and also written to a file named 'report'.

<next>

# Note the change in neighborhood composition for the one that moved.
# (note too that lines won't appear until you do a couple of steps.)

<next>
<next>
<next>

# Each step, the agent that was unhappy will move,
# and then another unhappy agent (or maybe the same one, if its 
# still unhappy and happened to be activated again) 
# will be picked for moving.

# Now lets run a number of steps by pressing

<start>

# Notice the degree of segregation is going up,
# as measured by the various aggregate values.
# Eventually, the agents will (probably) reach a 
# a equilibrium state, where everyone is happy.

<stop>

# we can start and stop as often as we want.
# we can probe other agents.

<start>
...
<stop>

# lets change the attribute of the agent we probed,
# from 1 to 2 (or vice versa); just
# change the agentType value in the probe widget (and press enter).
# note after <next> is pressed, the neighborhood stats are updated.

# We can also change agent types by MB1 (left) on them.
# Lets also first change oneStepMode to 0
# Now each time step all agents get one chance to move
# each time step (in a random order).

<change oneStepMode=0>

<next> ...

# after it stabilizes, MB1 on some fully segregated agent

<next> ...

# Sometimes that will create a cascade (i.e., cause
# neighborhoods to "tip"), sometimes not.
# (Its easier to see it after equilibrium is first reached.)

# Generally the agents rapidly find a stable state.
# But we can change a parameter and make it unstable again...

<change thresholdGreen=0.7>
<next..next...start...stop>

<start...stop>

# Again, after a while, it stabilizes.
# As expected, there is more segregation.

# But we also can add a little 'noise' in the form of
# rare random moves...what do you think that will do?
# Certainly some random moves will lead to some desegregation.
# But in the long term?

<change randomMoveProb=0.001>
<next..next...>
<start...stop>

# Note it becomes (eventually) segregrated into two groups;
# (modulo the noise)  Random moves -> more segregation!!
#
# NOTE: randomMoveProb only works with oneStepMode=0

# Note we can zoom in on graphs

<zoom in...hold mb1 and drag and release...>
<zoom out...mb3...>

<quit>

# Note too there is a new file in our directory

ll            <-- That's two el-characters!

head -30 report
tail -10 report 

# the report file has:
# a) all the parameter values used to start the run
#    (including the RNG seed), so we can repeat this run
# b) columns of data points vs t
# (Note in this case the "meaning" of t changed when we
# changed oneStepMode from 1 to 0.)

# the report file can be imported into other programs to
# do further analysis and plotting.

# we can also start the program with different parameters
# by putting them on the run command
# (note the \ at the end tells linux to continue reading the command
# on the next line):

tipping -DworldSize=30 -DmoveMethod=nearest-ok -DthresholdGreen=.50 \
  -DrandomMoveProb=0.001

# note those values are now the defaults in the GUI for those parameters

<start...start...quit>

# and we can exactly repeat that run...
# find the stop time:

tail -5 report

# use that to stop this next run which we run in "batch" mode:

tipping -DIF=report -DRN=repeat -DstopT=90 --batch

# we should have two report files now, and they
# should differ only in non-data ways:

ll
diff report report.repeat

#####################################################################
#
# Lets take a quick look at an IPD model...

cd ../IPD-m0
ipdm0 

# Again we get 3 widgets, with different model parameters.
# Let's see what this one does:
# Its actually a couple of models in one...

<writeHelp>

Let just use the simple non-moving version first...

<start,start> 

# note the C_f seems to go to a dynamic equilibrium value
# (the Wealth vs T is irrelevant for this set of parameters)

# we can look at one-step history...

<stop>
<toggleColorScheme>
<next...>

# we can probe agents and change agents...

<mb3 an agent...>
<mb1 that same agent...toggle its strategy, and color>
<next, next, ...>

# we can change the b (temptation) value...
# note the effect on the C_f

<toggleColorScheme>
<set b to 2.0  ... more temptation>
<start...>


<quit>

# again, there is a report file with details of this run.

ll 
head -30 report

#####################################################################

See the handout (also on the ICPSR course web page)

   demo-axelcult.txt

for a demo/explanation of the Axelrod Cultural Diversity model.

######################################################################