Quickstart guide and directory structure for the electronic supporting documentation
to the thesis 'Modelling an incremental theory of Lexical Functional Grammar' submitted to the University of Oxford on 3 July 2019.

The author's current contact details can be found via ORCID at 
https://orcid.org/0000-0003-2485-1566

************************
*** Quickstart guide ***
************************

THIS ASSUMES THAT YOU HAVE THE FOLLOWING ALREADY INSTALLED:
- ACT-R 7 VERSION 7.5-<2244:2017-07-11> - http://act-r.psy.cmu.edu/act-r-7-5/
   (Tested only with Source Code, not tested with Standalone Version)
- CLOZURE COMMON LISP - https://ccl.clozure.com/download.html
- GRAPHVIZ - https://graphviz.gitlab.io/download/


THE MODEL WILL NOT RUN OR GENERATE OUTPUT UNTIL YOU AMEND THE CODE
AS FOLLOWS SO THAT IT REFERENCES YOUR LOCAL FILE STRUCTURE

You need to know two filepaths: 
[ABSOLUTE PATH TO ACT-R] - the absolute path to the directory that holds the file load-act-r.lisp
[ABSOLUTE PATH TO MODULE] - the absolute path to the directory that holds these files  

1. In a text editor, open the file 'init.lisp' 

2. In line 7, replace [ABSOLUTE PATH TO ACT-R] with the actual pathway of the ACT-R directory, leaving "/load-act-r.lisp" at the end. ("\load-act-r.lisp" for Windows)

3. in line 15 replace [ABSOLUTE PATH TO ACT-R] with the actual pathway of the ACT-R directory  
-- if you are on Mac OSX leave "/environment/Start Environment OSX.app"  at the end
-- if you are on Windows, change the end to be "\environment\Start Environment.exe"

4. save and close 'init.lisp'

5. In a text editor, open the file 'timestamp.lisp'

6. In lines 30, 38, and 44, replace [ABSOLUTE PATH TO MODULE] with the actual pathway to this directory

7. save and close 'timestamp.lisp'



A - TO LOAD THE MODEL

1. open a terminal window

2. cd to the directory that holds the model files

3. start Clozure Common Lisp by entering 'ccl'

4. once Lisp is running, enter '(load "init.lisp")'

5. You should see the following error message:
	In STARTLFG: Undefined function START-ENVIRONMENT
   Ignore it.

6. Initialise the model by entering '(startlfg)'

7. The terminal should display the message "Opening the environment: enter OK when done :-)"

8. The ACT-R Environment will open. You may see error messages regarding the screen resolution and, for Mac OSX, a warning that future versions of the Start Environment app will not be compatible with OSX.

9. Once the ACT-R Environment has loaded, type 'OK' and enter in the terminal window.

10. The terminal should display the message "Loading the current model"

11. You will see a list of warnings about specific productions. These do not affect the running of the model.

12. Once the model is loaded you should see 
#P"[ABSOLUTE PATH TO MODULE]/lfgmodel.lisp"



B - TO RUN A SIMULATION FOR A SPECIFIC SENTENCE

1. In a text editor, open 'lfgmodel.lisp'

2. Lines 54-112 have functions that select a particular sentence. All but one of these are commented out with an initial semicolon. The example numbers after the functions refer to the examples given in the thesis.

3. To select a specific sentence, uncomment the relevant line by removing the semicolon. Ensure that all other test sentences are commented out.

4. Save 'lfgmodel.lisp'

5. Reload by entering '(reload)' in the ACT-R terminal window. The warning messages from step A12 above will show again

6. Run the model by entering '(run 10)' in the ACT-R terminal window.

7. Output will be added to a timestamped subirectory of a datestamped subdirectory of [ABSOLUTE PATH TO MODULE]/Outputs



C - TO VIEW THE OUTPUT

1. cd to the relevant timestamped subdirectory, which should contain a .csv file and a set of .gv files

2. Convert .gv files to .png files by running the script 'pngout' from the directory
[ABSOLUTE PATH TO MODULE]/Shell-scripts-graphics. This produces a .png file from each .gv file

3. The .gv/.png output file names ends with a two-digit index indicating at which point in the model run the output was generated.

4. The "final state" output file name is the last .gv/.png file to be added to the subdirectory. Its name ends with xx-00.gv/.png, as opposed to the opening state .gv/.png file, whose name ends with xx-00-00.gv/.png




***************************
*** Directory structure ***
***************************

Main directory - model code - functions of each file are indicated in the comments in init.lisp or lfgmodel.lisp

/Outputs - will hold the generated output from each run as described above

/Results-presented-in-thesis - holds .csv, .gv and .png files for the model runs whose output is presented in Chapter 6. Each example has a separate subdirectory for the results: the name of the subdirectory is [example number from thesis]-[name of variable in 'test-items.lisp' that was selected in 'lfgmodel.lisp' to generate the output]

/Shell-scripts-graphics - two shell scripts to generate .png files from the Dot language .gv files
