How Simile works

HereisasimpledescriptionofhowSimileexecutesamodelafterthediagramhasbeencreatedand
fullyspecified.

Running the model

Whenamodellergivestheinstructionto'run'amodel,Simileconvertsthemodeldiagramand
equationsintoac++programwhichiscompiledintoasharedlibrary.Thislibraryisimmediately
loadedintoSimileitself.Similetheninteractswiththelibrarytorunthemodelandobtainresults
whichcanthenbedisplayedorrecorded.
Theimportantcomponentsoftheprogramimplementingamodelareasfollows:

Aclassforeachsubmodelinthemodel'shierarchy,includingthetoplevel(desktop).Eachclass
containsavariableforeachcomponentinitssubmodel,anda'get_pointer'procedurefordecoding
numericalreferencestoitsvariables
An'update'procedure,whichadjuststhevaluesofthemodel'sstatevariablesateachtimestep
An'evaluate'procedure,whichcarriesoutalltheothercalculationsforagiventimestep,including
initializingstatevariableswhenthemodelisreset
Anarrayofdatastructurescontaininginformationabouteachcomponentinthemodel

Simile'smodelinteractionfunctionsareprovidedbyanothersharedlibrary,whichcanbelinked
againstbyotherapplicationprograms.Thisenablesthemtoloadsharedlibrariescorrespondingto
Similemodels,andtoexecutethosemodelsviatheirownuserinterface.Thegeneratedmodelcode
callsutilityproceduresinthislibrary,aswellasothersincodeincludedbythemodelprogram.

Serializing the network

Thefirstpartoftheprogrambuildingprocessconsistsofcreatingaprogramvariableforeach
primitivecomponentinthemodel,andaprograminstructiontogeneratethevalueofeachcomponent
fromthevaluesoftheothercomponentsonwhichitdepends.Thevariablesaregroupedintoclasses
correspondingtosubmodels.Inthecaseofacompartment,thevalueisdeterminedbyitsprevious
valueandthoseoftheflowsgoinginandoutofit;theydonothavetobeupdatedinanyparticular
order.Forothercomponents,thevaluemaybederivedfromthevaluesofothercomponentscalculated
earlierinthesameoperation,soorderingisimportant.
Theinstructionsthatcalculatethesevaluesaresortedbysearchingamongthemforthosewhichuse
onlycompartmentsandothervalueswhoseinstructionshavealreadybeenordered,andbuildingthe
resultsintoanorderedseriesofinstructionsdependingontheresultsofpreviousinstructions.Theseare
thenmadeintoaprocedurethatcalculatesthevaluesofallthemodelcomponents,startingfromthose
ofthecompartmentsandensuringthatnovalueiscalculatedbeforeallthoseonwhichitdependshave

beencalculated.
Acheckisdoneforsetsofinfluencesformingaloopbeforeserializationisattempted,since
serializationwillnotbepossibleifthereissuchacircularsetofinfluences.Theorderingeffectofan
influenceisdisabledifits'usevaluesfromthistimestep'propertyisselected,allowingmodelsto
includegraphicallyrepresentedcumulativeanditerativealgorithms.

Multiple instance submodels

Duringtheserializationprocess,Similemaintainsasubmodel'context'.Thisstartsatthetoplevelof
themodel(thedesktoplevel).Instructionsforeachcomponentcanonlybeputintoorderinthecontext
ofthesubmodelcontainingthatcomponent.Whennomoreinstructionscanbeorderedatthecurrent
level(e.g.,becauseeveryremainingvariableinthesubmodeldependsonavariableoutsideit)Simile
triestoswitchcontexttoasubmodelwithinthatlevel.Instructionswithinthatsubmodelcanthenbe
ordered.Ifthereisnothingthatcanbedoneinanychildsubmodelcontextitswitchestotheparent
context.
Thevaluesofmodelcomponentsinasubmodelarerepresentedasmembervariablesofaclasswhich
correspondstothesubmodel.Aninstanceofthisclassiscreatedforeachsubmodelinstance.Sections
ofthecodethatarecreatedinthecontextofamultipleinstancesubmodelareplacedwithinaprogram
loopwhichexecutesonceforeachinstanceofthesubmodel.Thevalueassignmentsuseapointer
whichpointstothecurrentinstanceofthesubmodelclassandisincrementedeachtimetheloopis
executed.Theimportanceofsubmodelcontextinserializationistominimizethenumberofprogram
loopsthatneedtobecreatedintheevaluationprocedure.Arrayvariablescanbeevaluatedoraccessed
inthesamecontextassubmodelswiththesamedimensions;inthiscasetheloopcountisusedasthe
arrayindex.
Functionsthatconvertanarrayintoascalarvaluecausean'intermediatevariable'tobecreated.Two
instructionsareaddedtoimplementthefunction;one,outsidethecontextoftheloopinwhichthearray
iscreated,toinitializetheintermediatevariable,andanotherinsidetheloopcontextbutafterthe
initializationandbeforetheinstructionthatevaluatestheequationcontainingthefunctionto
incrementorotherwisealtertheintermediatevariableoneachloopexecution.

Variable-membership submodels
Avariablemembershipsubmodelisrepresentedbyalinkedlistofinstancesoftheclasscorresponding
tothesubmodel.Foraconditionalsubmodel,thelistissetupatthestartofthefirstprogramloopin
whichvariablesinsidethesubmodelareevaluated.Thelistisinitiallyempty,andeachtimethe
membershipneedstobechecked,theprogramentersaloopoverallpotentialinstancesofthemodel
(asspecifiedbyitsdimensions).Ifaninstancedoesalreadyexist,itissnippedoutofthelist,otherwise
anewoneiscreated.Theinstanceisthenevaluatedasfarastheexistencecondition,atwhichpointit
iseitherdeletedorinsertedintothelist.Onsubsequentvisitstothatsubmodelcontext,theprogram
merelyloopsthroughallthemembersofthelist.

InSimile,avaluecomingoutofavariablemembershipsubmodelisknownaslistvalue.Functionscan
convertthistoascalarvalueasdescribedaboveforarrayvalues,butitcannotbeassignedasalisttoa
modelvariable.

Population submodels
Apopulationsubmodelisanotherkindofvariablemembershipsubmodel.Itisalsorepresentedbya
linkedlist,buthasseparategroupsofinstructionswithintheevaluateproceduretomanageits
membership.Beforefirstenteringthepopulation'scontext,aloopisenteredwhichdeletesallinstances
whichhavea'loss'componentwhoseconditionissatisfied.Then,newinstancesareappendedforany
individualsthathavebeenadded(includingtheinitialmembershipifthemodelisbeingreset).This
involvesaloopoverexistingmembersifthereisareproductionchannelinthepopulation.
Aconsequenceofthisisthatanindividualwillstillexistattheendofthetimestepinwhichits'loss'
conditionissatisfied,soeveryindividualexistsforatleastonetimestep.Thisallowsothermodel
actionstobetriggeredbythelossofanindividual.

Association submodels
Anassociationsubmodelisaspecialcaseofaconditionalsubmodel.Aswellasitsowndimensions,
theprocedurethatdeterminesitsmembershipisalsoenclosedinloopsthatiterateoverthe
membershipsofitsbasemodel(s).Whenevaluatingitsexistencecondition,valuesinthebasemodels
arereferencedbypointersthatareupdatedintheseloops.Ifanassociationsubmodelinstancedoes
exist,thesepointersarestoredwithinitsdatastructureinthesubmodel'slinkedlist.
Onsubsequentvisitstotheassociationsubmodelcontext,theprogramjustloopsthroughitsinstance
list.Referencestothebasemodelinstancesarehandledbythepointersthatwerestoredwithitduring
themembershiptest.Ifabasemodelhasan'exclusiverole'inanassociation,thenvariablesinthatbase
modelwhichdependonvaluesfromtheassociationmodelcanbeevaluatedwithintheassociation
model'scontext,since,ifthemembershipmeetsthedefinitionofanexclusiverole,thatwillresultin
thembeingevaluatedexactlyoncepertimestepineachbasemodelinstance.
Ifarolespecifiesthatthebaseinstanceislookedup,andtheassociationmodel'sconditionisofthe
appropriateform,thenthereisnoloopoverthisbasemodel'smembersinsteadtheindexiscalculated
fromtheassociationmodel'sconditionexpressionwhenevaluatingitsmembership,andapointertothe
basemodelinstanceisgeneratedfromthatindex.

Time steps
NoteveryvalueinaSimilemodelneedstobeevaluatedateverytimestep.Sowhentheevaluation
procedureiscalled,ithasanargumenttoindicatewhatactionisbeingtaken.Table1showswhat
actionsaredefined,andwhattheevaluationproceduredoesforeachofthem.Eachactionincludesall
thoselistedbelowit.

Actiontaken

Implementation

Initialize

Setliteralconstants

Resetafterloadingfixedparameters

Setfixedparametersfromfile

Normalreset

Setcompartmentstoinitialvalues
Setrandomconstants

Longesttimestep

Setvariableparametersandcompartmentsin
submodelsusingthattimestep

Shortertimestep

Setvariableparametersandcompartmentsin
submodelsusingthattimestep

Anyothermodelvariableissetinthefirstactionthatsetseveryvalueonwhichitdepends.For
instance,ifavariableiscalculatedexclusivelyfromfixedparameters,thenitwillbesetwhenthe
modelisinitializedorresetafterloadingfixedparameters.Itwillnotbesetonanordinaryresetor
duringsubsequentexecution.Inaddition,novariablewillbesetonashortertimestepthanthat
specifiedforitsownsubmodel.
Membershipsofconditionalsubmodelscanalsobesetinthefirstactionthatdeterminesallthevalues
onwhichtheydepend.Whenanewsubmodelinstanceiscreateditgetsaflagsayingitisnew,andthis
hastheeffectthatallvaluesinthatinstancearesetwhateveractionisbeingtaken.Theflagisclearedat
thestartofthenextevaluation.

Integration methods
Aswellasthe'evaluation'proceduredescribedabove,an'update'procedureisgeneratedforthemodel.
Thisiswhatadjuststhevaluesofcompartmentsaccordingtothevaluescalculatedfortheirflowsby
theevaluationprocedure.Theupdateproceduretakesasimilarformtotheevaluationprocedure,with
programloopsaroundthegroupsofstatementsthatapplytocompartmentsinmultiinstance
submodels,butthereisnoorderingrequirement,astheincrementsforeachcompartmentdonot
dependdirectlyonothercompartments.Thismeansthatthereisonlyeveroneprogramloopforeach
submodel.
Foreachcompartment,the'update'procedurecallsautilityprocedureintheincludedcode(the
'increment'procedure),withinloopsoverarraysorlistsofsubmodelinstances.Thisprocedureis
passedthenetsumofflowsinandoutofthecompartment,thetimestepidentityassignedtothe
submodel,andapointertoadatastructureassociatedwiththecompartmentinitssubmodelclass.The
valuereturnedbytheincrementprocedureisaddedtothecompartment'spreviousvaluewithinthe
updateprocedure.
WhenEulerintegrationisselected,thereturnvalueissimplythenetsumofflowsmultipliedbythe
timestepduration(calculatedastheelapsedmodeltimesincecompartmentsinsubmodelswiththat

timestepidentitywerelastupdated).Thecompartment'sassociateddatastructureisnotused.
WhenexecutingwithEulerintegration,Similerunstheupdateprocedurethentheevaluation
procedure,thenincrementsthemodeltimebytheshortestspecifiedtimestep.Thiscycleisrepeated
untilthespecifiedexecutionperiodiscompleted.Iftheincrementinmodeltimetakesitpastthe
boundaryofalongertimestepthantheshortest,the'action'passedtotheevaluationandupdate
proceduresissettotheidentityofthistimesteptoindicatethatvaluesthatonlychangeonthislonger
periodshouldalsobeupdatedandevaluated.
Similealsoallowsmodelexecutionwith4thorderRungeKuttaintegration.Themodelcodeisthe
same,butnowtheupdateandevaluationproceduresarecalledalternatelyfourtimeseachmodeltime
step.Themodeltimeisincrementedbyhalftheshortesttimestepbeforethefirstandthirdcallstothe
evaluationprocedure.Eachtimetheupdateprocedureiscalled,aglobalvariableissettoindicatethat
RungeKuttaintegrationisbeingdone,andwhichupdateinthesequenceisbeingmade.Thisvariable
affectsthebehaviouroftheincrementprocedure.Dependingonitsvalue,theincrementprocedure
returnsthevalueneededtosetthecompartmenttowhatitshouldbeforthenextstageoftheRunge
Kuttaalgorithm,orinthecaseofthelastupdateofthesequence,toitsfinalvalueasdeterminedbythis
algorithm.Thecompartment'sassociateddatastructureisusedtostoreintermediateresultsbetween
differentupdatesinthesequence.Thebehaviouroftheevaluationprocedureisthesameeachtimeitis
calledinthesequence,butitisstartingwithdifferent,partiallyincrementedcompartmentvalueseach
time.
Thedetailisbestexpressedbythecodeitself(procedurestage_incrinfilessupport2.cppand
support.tcl,andprocedurerk_updateinshank.cppandsupport.tcl,inSimile'sRundirectory,shank.cpp
onlydistributedinUnixversions),andadescriptionoftheRungeKuttaintegrationalgorithm,suchas
thatinNumericalRecipesinPascalbyPress,Flannery,TeukolskyandVetterling(Cambridge
UniversityPress,1989).