aires user's manual and reference guide

AIRESA system for air sho wer sim ulations

User’s guide and reference manual

Version 2.6.0

S. J. Sciutto

Departamento de FısicaUniversidad Nacional de La Plata

C. C. 67 - 1900 La PlataArgentina

[email protected]

July 11, 2002

AI

R-showerExtendedSimulations

iii

iv

AIRES user’sguideandreferencemanualVersion2.6.0(2002)

S.J.Sciutto,La Plata,Argentina.

Thismanualis partof theAIRES2.6.0distribution. TheAIRESsystemis distributedworldwideas“free software” for all scientistsworking in educational/researchnon-profitinstitutions.Usersfrom commercialor non-educationalinstitutionsmustobtaintheauthor’swritten permissionbe-fore usingthesoftwareand/orits relateddocumentation.

Thepresentdocumentmakesobsoleteall thepreviousversionsof theAIRES user’s manualandreferenceguide.

NO WARRANTY. TheAIRES systemis providedin an “as is” basis,without warrantyof anykind, eitherexpressedor implied, including, but not limited to, the implied warrantiesof mer-chantabilityandfitnessfor aparticularpurpose.Theentirerisk asto thequalityandperformanceof the programis with the user. Shouldtheprogramprove defective, theuserassumesthecostof all necessaryservicing,repairor correction.In no eventwill theAIRESauthor(s),beliable toany userfor damages,includingany general,special,incidentalor consequentialdamagesarisingoutof theuseor inability to usetheSimulationSystem(including,but not limited to, lossof dataor databeingrenderedinaccurateor lossessustainedby the useror third partiesor a failure ofthe Systemto operatewith any otherprograms),even if the author(s)have beenadvisedof thepossibilityof suchdamages.

Productandcompany namesmentionedin this manualaretrademarksor tradenamesof theirrespectivecompanies.

Summar y

ThenameAIRES (AIR -shower ExtendedSimulations)identifiesa setof programsandsubroutinesto simulateparticleshowersproducedafter the incidenceof high energy cosmicrayson theEarth’satmosphere,andto manageall therelatedoutputdata.

AIRES providesfull space-timeparticlepropagationin a realisticenvironment,wherethechar-acteristicsof theatmosphere,thegeomagneticfield andtheEarth’s curvaturearetaken into accountadequately. A statisticalsamplingprocedure(theso-calledthinning) is usedwhenthenumberof par-ticlesin theshowersis exceedinglylarge. Thethinningalgorithmsusedin AIRES areunbiased,thatis, thestatisticalsamplingnever alterstheaveragevaluesof outputobservables.

Theparticlestakeninto accountby AIRES in thesimulationsare:Gammas,electrons,positrons,muons,pions,kaons,etamesons,lambdabaryons,nucleons,antinucleons,andnucleiup to

��.

Electronand muon neutrinosare generatedin certainprocesses(decays)and accountedfor theirenergy, but not propagated.Theprimaryparticlecanbeany oneof thealreadymentionedparticles,with energy rangingfrom lessthan1 GeV up to morethan1 ZeV ( �� eV). It is alsopossibletosimulateshowersinitiatedby “special” primaryparticlesvia a call to a user-written modulecapableof processingthe “first interaction”of theprimary andreturninga list of standardparticlessuitablefor beingprocessedby AIRES.

Among all the physicalprocessesthat may undergo the shower particles,the most importantfrom the probabilisticpoint of view aretaken into accountin the simulations.Suchprocessesare:(i) Electrodynamicalprocesses:Pair productionandelectron-positronannihilation,bremsstrahlung(electrons,positronsand muons),muonic pair production,knock-onelectrons( rays), Comptonandphotoelectriceffects,Landau-Pomeranchuk-Migdal (LPM) effect anddielectricsuppression.(ii)Unstableparticle decays,pions andmuons,for instance. (iii) Hadronic processes:Inelasticcol-lisions hadron-nucleusandphoton-nucleus,sometimessimulatedusingan externalpackagewhichimplementsa given hadronicinteractionmodel, like the well-known SIBYLL or QGSJETmodels.Photonuclearreactions.Nuclearfragmentation,elasticandinelastic.(iv) Propagationof chargedpar-ticles: Lossesof energy in themedium(ionization),multiple Coulombscatteringandgeomagneticdeflections.

The AIRES simulationsystemprovides a comfortableenvironmentwhereto perform reliablesimulationstaking advantageof presentday computertechnology: The Input DirectiveLanguage(IDL) is a setof simpledirectiveswhich allow for anefficient controlof theinput parametersof thesimulation.TheAIRESRunnerSystemis a powerful tool to managelong simulationtasksin UNIX

v

vi SUMMARY

environments,allowing theuserto coordinateseveraltasksrunningconcurrently, controllingtheevo-lution of a given job while running,etc. TheAIRESsummaryprogram processesthe internaldumpfiles generatedby themainsimulationprogram,andallows to obtaindatarelatedwith physicalob-servableseitherafter or during the simulations.Finally, the AIRESobject library providesa seriesof auxiliary routinesto processthedatageneratedby thesimulationprogram,in particularthedatacontainedin thecompressedoutputfiles, thedetailedparticledatafiles containingper-particleinfor-mationfor particlesreachingthe ground,crossingdifferentobservinglevels during their evolution,etc.

The presentversionof AIRES (2.6.0) representsa new releaseof the Air Shower SimulationSystemwheremany new featuresandalgorithm improvementshave beenaddedto it. The mostimportant additions for this newversion are summarizedin appendicesE and F.

Many of thedevelopmentspresentedfor thecurrentreleasewereperformedtaking into accountusers’suggestionsandremarks.Theauthoris indebtedto everybodythathave contactedhim (averylong list of personsindeed),eitherto reportabug or to make acommenton theprogram.

La Plata,July 2002.

Contents

Summar y v

1 Intr oduction 11.1 Structure of the main simulation programs . . . . . . . . . . . . . . . . . . . . 51.2 Computer requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3 Getting and installing AIRES . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 General characteristics of AIRES 112.1 The environment of an air shower . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.1.1 Coordinate system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.2 Atmosphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.1.3 The slant depth and the Earth’s curvature. . . . . . . . . . . . . . . . . 172.1.4 Range of validity of the “plane Earth” approximation . . . . . . . . . . 182.1.5 Geomagnetic field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.2 Air showers and particle physics . . . . . . . . . . . . . . . . . . . . . . . . . 202.2.1 Particle codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2.2 Interactions taken into account in the current version of AIRES . . . . 222.2.3 Processing the interactions . . . . . . . . . . . . . . . . . . . . . . . . 232.2.4 Random number generator . . . . . . . . . . . . . . . . . . . . . . . . 27

2.3 Statistical sampling of particles: The thinning algorithm . . . . . . . . . . . . 272.3.1 Hillas thinning algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . 282.3.2 AIRES extended thinning algorithm . . . . . . . . . . . . . . . . . . . . 292.3.3 How does the thinning affect the simulations? . . . . . . . . . . . . . . 30

2.4 Some typical results obtained with AIRES . . . . . . . . . . . . . . . . . . . . 36

3 Steering the sim ulations 453.1 Tasks, processes and runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2 The Input Directive Language (IDL) . . . . . . . . . . . . . . . . . . . . . . . . 45

3.2.1 A first example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463.2.2 Errors and input checking . . . . . . . . . . . . . . . . . . . . . . . . . 463.2.3 Obtaining online help . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

vii

viii CONTENTS

3.2.4 Physical units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.2.5 Carrying on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.3 More on IDL directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.3.1 Run control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.3.2 File directories used by AIRES . . . . . . . . . . . . . . . . . . . . . . 603.3.3 Defining the initial conditions . . . . . . . . . . . . . . . . . . . . . . . 613.3.4 Geomagnetic field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643.3.5 Statistical sampling control . . . . . . . . . . . . . . . . . . . . . . . . 663.3.6 Output table parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 663.3.7 Random number generator . . . . . . . . . . . . . . . . . . . . . . . . 67

3.4 Input parameters for the interaction models . . . . . . . . . . . . . . . . . . . 683.4.1 External packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683.4.2 Other control parameters . . . . . . . . . . . . . . . . . . . . . . . . . 69

3.5 Special primary particles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.5.1 Defining special particles . . . . . . . . . . . . . . . . . . . . . . . . . 713.5.2 The external executable modules . . . . . . . . . . . . . . . . . . . . . 72

4 Managing AIRES output data 774.1 Using the summary program AiresSry . . . . . . . . . . . . . . . . . . . . . . 77

4.1.1 The summary file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784.1.2 Exporting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794.1.3 The task summary script file . . . . . . . . . . . . . . . . . . . . . . . 81

4.2 Processing compressed particle data files . . . . . . . . . . . . . . . . . . . . 834.2.1 Customizing the compressed files . . . . . . . . . . . . . . . . . . . . 844.2.2 Using the AIRES object library . . . . . . . . . . . . . . . . . . . . . . 94

5 The AIRES Runner System 1015.1 Checking input files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015.2 Managing simulation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

5.2.1 Canceling tasks and/or stopping the simulations . . . . . . . . . . . . 1035.2.2 Performing custom operations between processes . . . . . . . . . . . 103

5.3 Concurrent tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.4 Some commands to manage dump file data . . . . . . . . . . . . . . . . . . . 106

5.4.1 Converting IDF binary files to ADF portable format. . . . . . . . . . . . 107

A Installing AIRES and maintaining existing installations 109A.1 Installing AIRES 2.6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

A.1.1 Installation procedure step by step . . . . . . . . . . . . . . . . . . . . 110A.2 Recompiling the simulation programs . . . . . . . . . . . . . . . . . . . . . . . 112

CONTENTS ix

B IDL reference manual 114B.1 List of IDL directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

C Output data table inde x 137

D The AIRES object librar y 144D.1 C interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144D.2 List of most frequently used library modules. . . . . . . . . . . . . . . . . . . 145

E Release notes 215E.1 Differences between AIRES 2.6.0 and AIRES 2.4.0 . . . . . . . . . . . . . . . 215E.2 Differences between AIRES 2.4.0 and AIRES 2.2.1 . . . . . . . . . . . . . . . 217

F AIRES Histor y 220

References 228

Index 231

List of Figures

1.1 Structureof AIRESsimulationprogram . . . . . . . . . . . . . . . . . . . . . . . . 71.2 Stackentriesversusthinninglevel . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.1 AIRES coordinatesystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.2 Meanmolecularweightof theatmosphereversusaltitude . . . . . . . . . . . . . . . 142.3 Densityof air versusaltitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.4 Verticalatmosphericdepthversusaltitude . . . . . . . . . . . . . . . . . . . . . . . 152.5 Verticalatmosphericdepthfor altitudeslargerthan10 km . . . . . . . . . . . . . . . 162.6 Hadronicmeanfreepaths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.7 Effectof thethinningon thelongitudinaldevelopmentof chargedparticles. . . . . . 312.8 Effectof thethinningon the �� lateraldistribution . . . . . . . . . . . . . . . . . 322.9 Effectof thethinningon the �� lateraldistribution . . . . . . . . . . . . . . . . . 332.10 AIRES thinningalgorithmand � � � � lateraldistribution . . . . . . . . . . . . . . . . 342.11 AIRES thinningalgorithmandweightdistributions . . . . . . . . . . . . . . . . . . 352.12 AIRES thinningalgorithm.Processortime requirements . . . . . . . . . . . . . . . 352.13 Longitudinaldevelopmentof

�� eV protonshowers. . . . . . . . . . . . . . . 372.14 Energy longitudinaldevelopmentof

�� eV protonshowers . . . . . . . . . . . 372.15 Lateraldistributionsfor asingle �� thinninglevel shower . . . . . . . . . . . . . 382.16 Energy distributionsfor asingle �� thinninglevel shower . . . . . . . . . . . . . 392.17 Meanarrival time distributionsfor �� eV showers . . . . . . . . . . . . . . . . . 402.18 Lateraldistributionsof gammaselectronsandmuonsfor inclinedshowers . . . . . . 412.19 �� and �� lateraldistributionsfor inclinedshowers(I) . . . . . . . . . . . . . . . . 422.20 �� and �� lateraldistributionsfor inclinedshowers(II) . . . . . . . . . . . . . . . . 43

3.1 SampleAIRES input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513.2 SampleAIRESterminaloutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553.3 A modulefor specialprimaryparticles. . . . . . . . . . . . . . . . . . . . . . . . . 733.4 Showeraxis-injectionpoint coordinatesystem. . . . . . . . . . . . . . . . . . . . . 74

4.1 SampleAIRESTSSfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824.2 Processingcompresseddatafiles,anexample . . . . . . . . . . . . . . . . . . . . . 99

x

List of Tables

1.1 Main characteristicsof theAIRESair shower simulationsystem.. . . . . . . . . . . 4

2.1 Linsley’s modelcoefficientsfor theUS standardatmosphere . . . . . . . . . . . . . 172.2 Total shower axislengthandslantpathversuszenithangle . . . . . . . . . . . . . . 182.3 AIRES particlecodesandnames. . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.4 AIRES particlegroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.1 Physicalunitsacceptedwithin IDL directives . . . . . . . . . . . . . . . . . . . . . 493.2 Predefinedsitesof theAIRES sitelibrary . . . . . . . . . . . . . . . . . . . . . . . 64

4.1 Fieldscontainedin the“beginningof shower” recordof compressedparticlefiles . . 854.2 Fieldscontainedin the“endof shower” recordof compressedparticlefiles . . . . . . 864.3 Fieldscontainedin the“externalprimary particle” recordof compressedparticlefiles 884.4 Fieldscontainedin the“specialprimary trailer record” of compressedparticlefiles . 884.5 Fieldscontainedin theparticlerecordsof compressedgroundparticlefiles . . . . . . 894.6 Fieldscontainedin theparticlerecordsof compressedlongitudinaltrackingparticle

files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914.7 Particlecodingsystemssupportedby AIRES library routines . . . . . . . . . . . . . 95

xi

Chapter 1

Intr oduction

Cosmicrays with energies larger than 100 TeV must be studied–at present–using experimentaldevices locatedon the surfaceof the Earth. This implies that suchkind of cosmicrayscannotbedetecteddirectly; it is necessaryinsteadto measurethe productsof the atmosphericcascadesofparticlesinitiated by the incident astroparticle. An atmosphericparticle shower begins when theprimarycosmicparticleinteractswith theEarth’satmosphere.This is, in general,aninelasticnuclearcollision that generatesa numberof secondaryparticles. Thoseparticlescontinueinteractingandgeneratingmoresecondaryparticleswhich in turn interactagainsimilarly astheirpredecessors.Thismultiplicationprocesscontinuesuntil a maximumis reached.Thentheshower attenuatesasfar asmoreandmoreparticlesfall below thethresholdfor furtherparticleproduction.

A detailedknowledgeof thephysicsinvolved is thusnecessaryto interpretadequatelythemea-suredobservablesand be able to infer the propertiesof the primary particles. This is a complexprobleminvolving many aspects:Interactionsof high energy particles,propertiesof theatmosphereandthegeomagneticfield, etc. Computersimulationis oneof themostconvenienttoolsto quantita-tively analyzesuchparticleshowers.

In thecaseof air showersinitiatedby ultra-highenergy astroparticles( "!#�� %$ eV), theprimaryparticleshave energiesthatareseveralordersof magnitudelargerthanthemaximumenergiesattain-ablein experimentalcolliders.Thismeansthatthemodelsusedto rule thebehavior of suchenergeticparticlesmustnecessarilymake extrapolationsfrom the dataavailableat muchlower energies,andthereis still no definitive agreementaboutwhat is the mostconvenientmodelto acceptamongtheseveralavailableones.

TheAIRES system1 is asetof programsto simulatesuchair showers.Oneof thebasicobjectivesconsideredduring the developmentof the software is that of designingthe programmodularly, inorderto make it easierto switchamongthedifferentmodelsthatareavailable,without having to getattachedto aparticularone.

Several simulationprogramsthat weredevelopedin the pastwerestudiedin detail in order togain experienceand improve the new design. Among suchprograms,the well-known MOCCA

1AIRES is anacronym for AIR -shower ExtendedSimulations.

1

2 CHAPTER 1. INTRODUCTION

codecreatedby A. M. Hillas [1] occupiesan outstandingposition: It hasbeensuccessfullyusedto interpretdatacomingfrom variousair shower experiments,canbe operatedin a wide rangeofprimary energies (from �� % eV to �� eV), andpermitsto performsimulationswith a relativelymoderateconsumptionof computerresources.

TheMOCCA programhasbeenextensively usedastheprimary referencewhendevelopingthefirst versionof AIRES[2] releasedin May 1997.Thephysicalalgorithmsof AIRES1.2.0arevirtuallyequivalentto thecorrespondingonesfrom MOCCA [3]. Thestructureof AIRES is designedto takeadvantageof presentday computers,andthereforethe new programrepresentsan improvementofthe MOCCA code,allowing the user to comfortablyperform simulationsbasedon the extensiveknowledgeon air shower processesthatis containedin MOCCA’ssourcelines.

It is importantto remark,however, that the presentversionof AIRES doesincludemany mod-ificationsto the original algorithmswhich canalter the program’s outputwith respectto that fromMOCCA. This impliesthatbothprogramsareno longerequivalent.

Anothercharacteristicof ultra-highenergy simulationsthatwastakeninto accountwhendevelop-ing AIRES is thelargenumberof particlesinvolved. For example,a �� eV shower containsabout�� secondaryparticles.Fromthecomputationalpointof view, this facthastwo mainconsequencesthat were speciallyconsideredat the momentof designingAIRES: (i) With presentday comput-ers,it is virtually impossibleto follow all thegeneratedparticles,andthereforea suitablesamplingtechniquemust be usedto reducethe numberof particlesactually simulated. The so-calledthin-ning algorithmintroducedby Hillas [4] or thesamplingalgorithmof Kobal,Filipcic andZavrtanik[5] representexamplesof suchsamplingmethods.(ii) The simulationalgorithmis CPU intensive,andthereforeit is necessaryto develop a seriesof specialproceduresthatwill provide anadequateenvironmentto processcomputationallylong tasks.

Therearemany quantitiesthat definethe initial or environmentalconditionsfor an air shower,for example,the identity of the primary particleandits energy, the positionof the groundsurface,theminimumenergy aparticlemusthave to betakeninto accountin thesimulation,theintensityandorientationof thegeomagneticfield, etc. Additionally, it is possibleto definemany observablesthatareusefulto characterizetheparticleshower, namely, longitudinalandlateraldistributionof particles,energy distributions,positionof theshower maximumandsoon.

A comfortableenvironmentis providedby AIRES to manageall the input andoutputdata:TheInput DirectiveLanguage (IDL) is a setof human-readableinput directivesthatallow theuserto ef-ficiently steerthesimulations.TheAIRESsummaryprogramandtheAIRESobjectlibrary representa set of tools to managethe outputdataafter the simulationsarefinished,andeven during them,allowing to controltheirevolution. Dataassociatedwith particlesreachinggroundor crossingprede-terminedobservinglevelscanberecordedinto compressedoutputfiles. A specialdatacompressionprocedureis usedto reduceasmuchaspossiblethesizeof thefiles, which tendsto bevery large incertaincircumstances.Thecompressedfilescanbeprocessedwith thehelpof someauxiliaryroutinesthatareincludedin theAIRES library. Themachineandoperatingsystemusedto generatesuchfilesmaybedifferentthattheonesusedto readthem.

As mentionedpreviously, thephysicalalgorithmsof theMOCCA simulationprogramdeveloped

CHAPTER 1. INTRODUCTION 3

by A. M. Hillas [1], wereusedastheprimaryreferencein theoriginal designof AIRES.As a result,theoutputdatacomingfrom MOCCA SP(1996)2 (mocorbin zg) andAIRESfirst version(1.2.0)[2]aresimilarwhenbothprogramsareinvokedwith equivalentinitial conditions3.

Theparticlestakeninto accountby AIRES in thesimulationsare:Gammas,electrons,positrons,muons,pions,kaons,etamesons,lambdabaryons,nucleons,antinucleons,andnucleiup to

��.

Electronand muon neutrinosare generatedin certainprocesses(decays)and accountedfor theirenergy, but not propagated.Theprimaryparticlecanbeany oneof thealreadymentionedparticles,with energy rangingfrom lessthan1 GeV up to morethan1 ZeV ( �� eV). It is alsopossibletosimulateshowersinitiatedby “special” primaryparticlesvia a call to a user-written modulecapableof processingthe “first interaction”of theprimary andreturninga list of standardparticlessuitablefor beingprocessedby AIRES. A detaileddescriptionon how to defineandusespecialprimariesisplacedin section3.5.

Among all the physicalprocessesthat may undergo the shower particles,the most importantfrom the probabilisticpoint of view aretaken into accountin the simulations.Suchprocessesare:(i) Electrodynamicalprocesses:Pair productionandelectron-positronannihilation,bremsstrahlung(electrons,positronsand muons),muonic pair production,knock-onelectrons( rays), Comptonandphotoelectriceffects,Landau-Pomeranchuk-Migdal (LPM) effect anddielectricsuppression.(ii)Unstableparticledecays,pionsandmuons,for instance.(iii) Hadronicprocesses:Inelasticcollisionshadron-nucleusandphoton-nucleus,generallysimulatedusinganexternalpackagewhichimplementsa givenhadronicinteractionmodellike thewell-known SIBYLL [6] or QGSJET[7] models;or by abuilt-in algorithmcalledextendedHillas splittingalgorithm(EHSA).Photonuclearreactions.Nuclearfragmentation,elasticandinelastic. (iv) Propagation of charged particles: Lossesof energy in themedium(ionization),multiple Coulombscatteringandgeomagneticdeflections.

All thegeneralcharacteristicsof AIRES andthephysicsinvolved in air shower simulationsaresummarizedin table1.1; they aredescribedin moredetail in chapter2.

AIRES is completelywritten in standardFORTRAN 77 (usinga few extensionsthatare,to thebestof our knowledge,acceptedby all FORTRAN compilers). The completeAIRES 2.6.0sourcecode,which includestheQGSJET4 [7] andSIBYLL 5 [6] hadroniccollisionspackages,theIGRF [8]routinesto evaluategeomagneticdataandNetlib/minpack/lmdernonlinearleastsquaresfitting pack-age[10], consistsof morethan670routines,addingup to morethan94,000sourcelinesextensivelycommented.

In thepresentversion,theAIRESsimulationsystemconsistsof thefollowing:

& Themainair showersimulationprograms,Air es, Air esQ, Air esS16, andAir esQ99, containing

2MOCCA SPis a newer versionof theMOCCA programwhich incorporatessomeimprovementswith respectto theoriginal versiondevelopedby A. M. Hillas.

3AIRES andMOCCA input parametersetsaredifferent,andthereforeinitial conditionsthat areequivalent for bothprogramscanbeaccomplishedonly in selectedparticularcases.

4The versionof QGSJETinstalledin AIRES 2.6.0 is dated12/Feb/2002,and is usually referredasQGSJET01.Anolderversionof QGSJETis alsoincludedwith thedistribution, thatcanbeusedto make comparisons.

5Theversionof SIBYLL installedin AIRES 2.6.0is theversion2.1,dated02/May/2002.An olderversionof SIBYLL[9] is alsoincludedwith thedistribution,thatcanbeusedto make comparisons.


Propagatedparticles Gammas.Leptons:'( , )�( .Mesons:*,+ , *�( ; - , ./+021 3 , .4( . Baryons:5 , 65 , 7 , 67 , 8 .Nuclei up to 9;:=<?> .Neutrinosaregenerated(in decays)andaccountedfor theirnumberandenergy, but not propagated.

Primary particles All propagatedparticlescanbeinjectedasprimaryparticles.Multiple and/or“exotic” primariescanbeinjectedusingthespecialpri-maryfeature.

Primary energy range From800MeV to 1 ZeV ( @�A?B�C eV).

Geometryand envir onment Incidenceanglesfrom verticalto horizontalshowers.TheEarth’scurvatureis takeninto accountfor all inclinations.Realisticatmosphere(Linsley model).Geomagneticdeflections:Thegeomagneticfield canbecalculatedus-ing theIGRFmodel[8].

Propagation(general) Mediumenergy losses(ionization).Scatteringof all chargedparticlesincluding correctionsfor finite nu-clearsize.Geomagneticdeflections.

Propagation: Electronsandgammas

Comptonandphotoelectriceffects.Bremsstrahlungand 'EDF'HG pair production.Emissionof knock-onelectrons.Positronannihilation.LPM effect,anddielectricsuppression.Photonuclearreactions.

Propagation: Muons Bremsstrahlungandmuonicpairproduction.Emissionof knock-onelectrons.Decay.

Propagation: Hadronsandnuclei

Hadronic collisions using the EHSA (low energy) and QGSJETorSIBYLL (highenergy).Nuleus-nucleuscollisionsvia QGSJETor SIBYLL, or usinga built-innuclearfragmentationalgorithm.Hadroniccrosssectionsare evaluatedfrom fits to experimentaldata(low energy), or to QGSJETor SIBYLL predictions(highenergy).Emissionof knock-onelectrons.Decayof unstablehadrons.

Statistical sampling Particlesare sampledby meansof the Hillas thinning algorithm [4],extendedto allow controlof maximumweights.

Main observables Longitudinaldevelopmentof all particlesrecordedin up to 510observ-ing levels.Energy depositedin theatmosphere.Lateral,energy andtimedistributionsatgroundlevel.Detailed list of particlesreachingground, and/or crossingpredeter-minedobservinglevels.

Table1.1.Main characteristicsof theAIRESair showersimulationsystem.


theinterfaceswith thehadroniccollisionpackagesSIBYLL 2.1,QGSJET01,SIBYLL 1.6,andQGSJET99,respectively.

& The summaryprogram(Air esSry) designedto processa part of the datageneratedby thesimulationprograms,allowing theuserto analyzetheresultsof thesimulationaftercompletingit, or evenwhile it is beingrun.

& TheIDF to ADF file formatconvertingprogramAir esIDF2ADF.

& A library of utilities to help theuserto processthecompressedoutputdatafiles generatedbythe simulationprogram,write externalmodulesto processspecialprimaries,etc. In UNIXenvironmentsthis library is implementedasanobjectlibrary calledlibAir es.a.

& TheAIRES runnersystem:A setof shell scriptsto easeworking with AIRES in UNIX envi-ronments.

& A seriesof PAW [11] macroscapableof downloadingAIRES outputdatadirectly from withinthisanalysisprogram.

1.1 Structure of the main sim ulation programs

An air shower startswhen a cosmicparticle reachesthe Earth’s atmosphereand interactswith it.In mostcasesthefirst interactionis an inelasticcollision of the (high energy) primaryparticlewithan air nucleus. The productof this collision is a set of secondaryparticlescarrying a fraction oftheprimary’s energy. Thesesecondariesbegin to move throughtheatmosphereandwill eventuallyinteractsimilarly astheprimarydid, generatingnew setsof secondaries.This multiplicationprocesscontinuesuntil a maximumis reached.After thatmomenttheshower beginsto attenuatebecauseanincreasingnumberof secondariesareproducedwith energiestoo low for furtherparticlegeneration.

Thisphenomenonis simulatedin AIRES in thefollowing way:

1. Severaldataarraysor stacksaredefined.Everyrecordwithin any stacksis aparticleentry, andrepresentsaphysicalparticle.Thedatacontainedin every recordarerelatedto thecharacteris-tics of thecorrespondingparticle:Identity, position,energy, etc.

2. Theparticlescanmove insidea volumewithin theatmospherewheretheshower takesplace.Thisvolumeis limited by theground,andinjectionsurfaces,andby verticalplaneswhichlimittheregion of interest.

3. Beforestartingthesimulationsall thestacksareempty. Thefirst actionis to addthefirst stackentry, whichcorrespondsto theprimaryparticle.Theprimaryis initially locatedattheinjectionsurface,andits downwardsdirectionof motiondefinesthesower axis.


4. Thestackentriesarerepeatedlyprocessedsequentially. Everyparticleentryis updatedanalyz-ing first all thepossibleinteractionsit canhave,andevaluatingthecorrespondingprobabilitiesfor eachpossibility, takinginto accountthephysicsinvolved.

5. Using a stochasticmethod,the mentionedprobabilitiesareusedto selectoneof thepossibleinteractions.This selectiondefineswhat is goingto happenwith thecorrespondingparticleatthatmoment.

6. The interactionis processed:First the particle is moved a certaindistance(which comesoutfrom thementionedstochasticmethod),thentheproductsof theinteractionaregenerated.Newstackentriesareappendedto theexisting lists for every oneof thesecondaryparticlesthatarecreated.Dependingon the particularinteractionthat is beingprocessed,the original particlemay survive (the correspondingentry remainsin the stackfor further processing)or not (theentryis deleted).

7. Whenachargedparticleis moved,its energy is modifiedto take into accounttheenergy lossesin themedium(ionization).

8. Particleentriescanalsoberemovedwhenoneof thefollowing eventshappens:(a)Theenergyof theparticleis lower thana certainthresholdenergy calledcut energy. Thecut energiesmaybe different for differentparticlekinds. (b) The particlereachesgroundlevel. (c) A particlegoingupwardsreachestheinjectionsurface.(d) A particlewith quasi-horizontalmotionexitstheregion of interest.

9. After having scannedall thestacks,it is checked whetheror not thereareremainingparticleentriespendingfurtherprocessing.If theansweris positive, thenall thestacksarere-scannedoncemore;otherwisethesimulationof theshower is complete.

Thegroupof algorithmsrelatedwith interactionselectionandprocessing,aswell ascalculationof energy lossesis thegroupof physicalalgorithms. In thecurrentversionof AIRES many of suchalgorithmsareequivalentor similar to theonesimplementedin theprogramMOCCA [1].

Themostimportantair shower observablesarethoserelatedwith statisticaldistributionsof par-ticle properties.To evaluatesuchquantitiesthesimulationengineof AIRES alsopossessesinternalmonitoring proceduresthat constantlycheckand recordparticlesreachinggroundand/orpassingacrosspredeterminedobservingsurfaceslocatedbetweenthegroundandinjectionlevels.

From this description,it shows up clearly that the air shower simulationprogramsconsistofvariousinteractingproceduresthatoperateonadatasetwith avariablenumberof records,modifyingits contests,increasingor decreasingits sizeaccordinglywith predeterminedrules.

It is necessaryto do a modulardesignof sucha programto make it moremanageable;andthisis particularly relevant for the caseof the algorithmsrelatedwith the physical laws that rule theinteractionswhere–asmentioned–therearestill openproblemsrequiring continuouschangeandtestingof procedures.


Input fileLog, sry, and tssfiles

Exportedtables

I J

IDL parser Log andsummary units

Initializationand input check Job control

Math andphysical data

routines

Systemutilities

K K K K K K K K K

LLLLLLLLLKERNEL

Particlestack

managerSpecial

primaries

INTERA CTIONMODELS

Monitoringroutines

ExternalPackages

Particle dataoutput

ICompressedoutputfile(s)

Figure 1.1. Thestructure of AIRESmainsimulationprogram.


Figure1.1 containsa schematicrepresentationof the modularstructureof the main simulationprograms.Everyunit consistsof asetof subroutinesperformingthetasksassignedto thecorrespond-ing unit. In general,everyunit canbereplacedvirtually withoutalteringtheotherones.In thecaseoftheexternalinteractionmodelswherecompletepackagesdevelopedby othergroupsarelinkedto thesimulationprogramvia a few interfaceroutines,themodularityacquiresparticularimportancesinceit makesit possibleto easilyswitchamongthevariouspackagesavailable.

The usercontrolsthe simulationparametersby meansof input directives. The Input DirectiveLanguage (IDL) is a setof human-readabledirectivesthanprovidesa comfortableenvironmentfortaskcontrol. After the input datais processedandchecked, control is transferredto the program’skernel. During the simulationsthe particlesof the cascadearegeneratedandprocessedby severalpackages.Theinteractionsmodelpackagecontainsthe“physics”of theproblem.

Thejob controlunit is responsible(amongothertasks)of updatingthe internal dumpfile (IDF).This file containsall therelevant internaldatausedduring thesimulation,andis thekey for systemfault tolerantprocessingsinceit makesit possibleto restartabrokensimulationprocessfrom thelastupdateof theIDF.

Thekernelinteractsalsowith othermodulesthatgeneratetheoutputdata,namely, log, summary,andtasksummaryscript files, internaldumpfile –in eitherbinaryor ASCII (portable)format–andcompressedoutputfilesgeneratedby themonitoringroutinesandtheparticledataoutputunit.

In thecurrentversionof AIRES,therearetwo compressedoutputfiles implemented:Thegroundparticlefile andthelongitudinaltrackingparticlefile. Recordswithin thegroundparticlefile (longitu-dinal trackingfile) containdatarelatedwith particlesreachinggroundlevel (passingacrossobservinglevels).

Sincethenumberof datarecordscontainedin suchfiles canbeenormous,aspecialcompressionmechanismhasbeendevelopedto reducefile sizerequirements.Thecompressingalgorithmis partof theparticledataoutputmodule.To give anideaof thespaceneededto storetheparticlerecords,let usconsiderthecaseof thegroundparticlefile with its default settings:For eachparticlereachinggroundandfulfilling certain(usersettable)conditions,a 18 byte long recordis written. Therecorddataitemsare: particleidentity, statisticalweight,position,time of arrival anddirectionof motion.Leadingandtrailing recordsarewrittenbeforeandafteranindividualshoweriscompletelysimulated.Considering,for instance,a “hard” simulationregime where M � �� %$ eV primary energy showers(protonor iron) aresimulatedwith ��N�PO relative thinning level usingthe standardHillas algorithm(seesection2.3), generatea compressedgroundparticlefile of sizelessthan11 MB/shower whenstoringall theparticleswhosedistancefrom theshowercoreis largerthan50m andlessthan12km.

The greenunit named“specialprimaries”consistsbasicallyin a kernel-operatedinterfacewithuser-provided externalmodulescapableof generatinglists of particlesthatwill beusedto initiate ashower. This featureallows theuserto startshowersinitiatedby non-conventional(exotic) primaryparticleslike neutrinos,for example.

Themathandphysicaldataroutinesarecalledfrom severalunitswithin theprogramandprovidemany utility calculations. In particular, they containthe atmosphericmodel (usedto accountforthevaryingdensityof theEarth’s atmosphere)andthegeomagneticfield auxiliary routinesthatcan


evaluatethegeomagneticfield in any placearoundtheworld.

1.2 Computer requirements

Thecomputerrequirementsto simulateair showerslargely dependuponthecharacteristicsof eachparticulartask.In particular, CPUtimerequirementscanbeveryhard,speciallywhenthesimulationsaredoneusinglow thinningenergies(For example, RQTSEUWV�VEUWVEXZY#�� PO \[E] UW^�_ ]a` .)

UsingtheHillas thinningalgorithm(seesection2.3.1),andconsideringtherepresentative caseofb � �� %$ eV protonshowerswith 40deg zenithangle,it is easyto verify thattheCPUtimepershowerscaleslinearlywith ced�fFgh \[E] UW^�_ ]a`�ij \QaSEUWVEV�UWVEXlk : TheCPUtimepershower increasesroughlyin a factorof 8 when \[E] UW^�_ ]m`�ij RQaSEUWVEVEUWVEX is increasedin oneorderof magnitude.To giveanestimationof theab-soluteamountof timeneededtosimulateoneshower, it canbementionedthatin aPentiumII machine(300Mhz clock)usingLinux OStheCPUtime for asingleshower with \[E] UW^�_ ]m`�ij \QaSEUWVEVEUWV�X � �� isabout12minutes.Thisprojectsontosome12 and100hoursfor �� O and �� respectively.

TheCPUtimedependsonotherparametersbesidesthethinningandprimaryenergies(seesection2.3.3). The inclinationof theshower axis (zenithangle)is oneof them. TheCPU time pershowergenerallyincreaseswhenthe zenithangleis enlarged: A 45 deg (85 deg) inclined shower requiresroughly1.3(1.6) timesmoreCPUtime thataverticalone.

It is importantto saythat thealgorithmsthat take into accountthecurvatureof theearthandtheeffect of the geomagneticfield weredesignedin sucha way that their CPU time requirementsarenot importantwhencomparedwith the overall requirementsof the simulatingengine. As a result,theCPUtime pershower neededto performsimulationsusingthecurrentAIRESversion(2.6.0)areessentiallythesameasthecorrespondingonesof version1.2.0,even for showerswith large zenithangleswherethesphericalearthcalculationsbecomeimportant[12].

Memoryrequirementsdependbasicallyuponthesizeof thestackarea(setat compilationtime).With the default areasizeof 5 MB (Megabytes),the programusesabout9 MB of randomaccessmemory. Disk storagerequirementsdependon thestackareasize,thinninglevel, and(for theoutputcompressedfiles) on the numberandkind of showers to be simulated. Internalprocedurescreatesomescratchfiles whosesizecanbeaslargeasseveral tensof MB6. Thesizeof the largestscratchfiles is directly correlatedto the total numberof processedparticles. In figure 1.2, the numberofprocessedparticlesis plottedversusthethinninglevel. It is evident that theprocessedparticles(andhencetheharddiskspacerequirements)grows significantlywhenthethinningenergy is lowered.

1.3 Getting and installing AIRES

AIRES is distributedworldwideas“free software” for all scientistsworking in educational/researchnon-profit institutions. Usersfrom commercialor non-educationalinstitutionsmustobtain the au-thor’s writtenpermissionbeforeusingthesoftware.

6Thescratchfilescanoccupy about100MB in someextremecircumstances


1e4

1e6

1e8

3 4 5 6 7 8

Pro

cess

ed p

artic

les

n

-log10(Eth/Epr)

Gammas, e+ e-

Heavy particles

Figure 1.2.Numberofprocessedstack entries(particles)asa functionof thethinninglevel. Theshowerswere initiated by opNq%r eVprotons,with verticalincidenceandgroundlevellocatedat 1000gs cmt .

Thepresentversionof AIRES(2.6.0)canbeobtainedfrom theWorld WideWeb,at thefollowingaddress:

http://www.fisica.unlp.edu.ar/auger/aires

AIRES is distributedin theform of a compressedUNIX tar file. Theinstallationis automaticforUNIX systems.For otheroperatingsystemssomeadaptive work maybeneeded.AppendixA (page109)containsdetailedinstructionson how to installAIRESand/ormaintainanexisting installation.

Chapter 2

General characteristics of AIRES

The aim of this chapteris to introducethe basicconceptsneededto adequatelydefinethe problembeingconsidered.

2.1 The envir onment of an air sho wer

2.1.1 Coor dinate system

The AIRES coordinatesystemis a Cartesiansystemwhoseorigin is placedat sealevel at a user-specifiedgeographicallocation. The uwv planeis locatedhorizontallyat sealevel and the positivex -axispointsupwards.The u -axispointsto the“local” magneticNorth, that is, thelocal directionofthehorizontalcomponentof thegeomagneticfield (seesection2.1.5for details).The v -axispointstotheWest.

Figure2.1 shows anschematicrepresentationof thecoordinatesystemusedby AIRES. The uwvplaneis tangentto the sealevel surface,heretaken asa sphericalsurfaceof radius y{z}|�~��jp��j�l�m centeredat theEarth’s center. Thegroundlevel,andthe injectionlevel, referto sphericalsurfacesconcentricto thesealevel surfaceandintersectingthe x -axisat x | x� ( x�� p ) and x | x� ( x��x� )respectively.

The showeraxis of a shower with zenithangle � is definedasthe straightline that passesbytheintersectionpoint betweenthegroundlevel andthe x -axis,andmakesanangle � with the x -axis( p��p�� ). Theazimuthangle � is theanglebetweenthehorizontalprojectionof theshoweraxisandthe u -axis( p��~�p�� ).

In AIRES version1.2.0,all the sphericalsurfacesmentionedin the precedingparagraphswereapproximatedasplanes.This approximationis justifiedevery time thehorizontaldistancesinvolvedarenegligible in comparisonwith theEarth’s radius, y{z . This is thecasefor showerswhosezenithangleis small, but certainlynot for thosewith large zenithangles,especiallyfor quasi-horizontalshowers.

For AIRESversion1.4.0or laterthecurvatureof theEarthis takeninto accountto make it possi-bleto reliablysimulateshowerswith zenithanglesin thefull rangep/��p�� . Sincefull spherical

11

12 CHAPTER 2. GENERAL CHARACTERISTICS OF AIRES

�

�

�

��

�H�

Sea levelGround level

� 22 km

Limits of “planeEarth” zone

Shower

axis

Figure 2.1.AIREScoordinatesystem.

calculationsarecomputationallyexpensive, aneffort wasmadeto optimizethecorrespondingalgo-rithms.Theseoptimizationsarebasedontwo key concepts:(i) Evenif anon-verticalshowercanstartin a very distantpoint, mostof theshower developmenttakesplacerelatively nearthe x -axiswherethe“planeEarth”approximationis acceptable.(ii) Many calculationsthatemploy sphericalgeometrycanbe substantiallysimplified if thecoordinatesystemis temporarilyrotatedso the involved pointlies nearthenew x -axis,andplanegeometryis usedin the rotatedsystem.If necessary, an inverserotationis appliedto expressresultsin theoriginal coordinatesystem.

In order to apply the first concept,a zonewherethe Earthcanbe acceptablyapproximatedasplanemust be defined. As it will be justified later in this chapter(seesection2.1.4), the Earth’ssphericalshapecanbeignoredin aconicregionregioncenteredatthe x -axis,with avaryingdiameterrangingfrom 8 km at sealevel to 45 km at an altitudeof 100 km.a.s.l. The averagelimits of thatregion (about22 km diameter)areindicatedin figure2.1.

To fastlyperformtherotationoperationsneededto expresscoordinatesandvectorin a temporarylocalcoordinatesystem,it resultsconvenientto usearedundantsetof coordinates,definedasfollows:Let ¡ bethepositionvectorof a point with coordinates¢Tu�£¤vP£ xN¥ . We definethevertical altitude, x�¦ ,of thepointastheminimumdistancebetweenthepointandthesealevel surface.It is straightforwardto demonstratethat ¢hy{z¨§ x�¦�¥ t |�¢hy{z�§ x � ¥ t §ª© t (2.1)

CHAPTER 2. GENERAL CHARACTERISTICS OF AIRES 13

where©2t«|�uPt¨§=vNt and x � | x denotesthepoint’s central altitude, analternative way to expressthex -coordinatewhich stressesthe fact that this coordinateis alwaysmeasuredalongthe samecentralaxis.Theredundantsetof coordinates ¢Tu�£¤v�£ x � £ x¦�¥ (2.2)

is usedby AIRESto definethepositionof apoint. Thedifferencebetweenx � and x¦ givesinformationabouthow far from the x -axisis thepoint,andin the“planeEarth” zone x¦ is setequalto x � .

Thiswayof takinginto accounttheEarth’sshapein thesimulationsprovedto beaccurateenoughwhencomparedwith exactprocedureswhile beingeconomicfrom thecomputationalpoint of view,asshown in section1.2(page9).

2.1.2 Atmosphere

TheEarth’satmosphereis themediumwheretheparticlesof theshowerpropagateandtheirevolutiondependsstronglyon its characteristics.Thesimulationsmustthereforebebasedon realisticmodelsof therelevantatmosphericquantities.

Theatmospherehasbeenextensively measuredandstudiedduringthe lastdecades.As a result,a varietyof modelsandparameterizationsof measureddatahave beenpublished.Amongthem,theso-calledUSstandard atmosphere [13] is awidely usedmodelbasedonexperimentaldata1. Wehaveselectedit asa convenientmodelto usein AIRES whichgivesanacceptablyrealisticapproximationof theaverageatmosphere.

An evidentcharacteristicof theatmosphericmediumis thatof beinginhomogeneous.Its density,for instance,diminishessix ordersof magnitudewhenthealtitudeabove sealevel passesfrom zeroto 100km, andanotheradditionalsix ordersfor therange100km to 300km [14]. This fact is takeninto accountin themodelwe have selected,wheremostof the relevantobservablesareregardedasfunctionsof thealtitudeabove sealevel, or verticalaltitude, ¬ : Theatmosphereis thusa sphericallysymmetric“layer” a few hundredskilometersthick, whoseinternalradiusis theEarth’s radius(6370km).

For a varietyof processesthattheparticlescanundergo duringthedevelopmentof theshower, itis essentialto know thechemicalcompositionaswell asthedensityof themediumthey arepassingthrough[15]. For this reason,we have studiedthebehavior of thesetwo quantities,especiallytheirdependencewith theverticalaltitude.

The chemicalcompositionof the air, asgiven by themeanmolecularweight, remainsvirtuallyunchangedin all the region p�®¬#�®��p km, anddiminishesprogressively for larger valuesof ¬ .This clearlyshows up in figure2.2,wheretheUS standardatmospheremeanmolecularweight [14]hasbeenplottedversustheverticalaltitude.Theconstantvalue ¯ |±°�²N³´��~�~ is themeanmolecularweight correspondingto an atomic mixture of 78.47%N, 21.05%O, 0.47%Ar and 0.03%otherelements. The correspondingmeanatomic weight (atomic number)is 14.555(7.265). The ratiobetweenmeanatomicnumberandweightis 0.499.

1The US standardatmosphereis sometimesreferredas the US extensionof the ICAO (InternationalCivil AviationOrganization)standardatmosphere.


16

20

24

28

32

0.1 1 10 100

M (

g/m

ol)

µ

h (km)

28.966

Figure 2.2.Meanmolecularweightof theatmosphere asafunctionof theverticalaltitude(USstandardatmosphere [14]). Theline isonly to guidetheeye.

On theotherhand,thedensityof theair doeschangeconsiderablywith thevertical altitude,asshown in figure2.3. ThedotsaretheUS standardatmospheredata,taken from reference[14]. Thegreenfull line correspondsto Linsley’s parameterizationof the US standardatmosphere[16], alsocalledLinsley’s atmosphericmodelor Linsley’s model,whicheffectively reproducesvery accuratelytheUS standardatmospheredata.Theisothermalatmosphere

©w¢¶¬ ¥ |·©2¸�¹�º �¼»}½?¾�¿ÁÀ (2.3)

wasalsoplotted(dottedred line) for comparison. ©N¸ and Â matchthe correspondingUS standardatmospherevaluesat sealevel.

1e-6

1e-3

1.00

0.1 1 10 100

Den

sity

(kg

/m3)

h (km)

I.A. L.M.S.A.

Figure 2.3.Densityof theairasa functionof theverticalaltitude. ThedotsrepresenttheUSstandard atmospheredata[14], while thefull greenline correspondsto Linsley’smodel[16] andthedashedredoneto theisothermalatmosphere©w¢¶¬ ¥ |·©2¸�¹ º �¼»}½?¾�¿ÁÀ with© ¸ |±o�³´°�°�Ã kgs mÄ ,¯Å|�°�²N³´��~�~ and Â�|�°�²�² K.

It is worthwhilementioningthatLinsley’s modelis limited to altitudes ¬Æ��¬ÁÇ�ÈÊÉ with ¬,Ç�ÈÊÉ4|o�o�°N³´² km. Thedensityis consideredto bezerofor ¬ � ¬ Ç�ÈÊÉ . This approximationhelpsvery muchto simplify differentalgorithmsusedin air shower simulationswhile beingabsolutelyjustifiedsinceonly affectsan atmosphericzoneplacedmuchabove the region wherethe air showers take place,whichatmostextendsup to 50verticalkilometersabove sealevel.


0

100

200

300

400

500

600

700

800

900

1000

0.1 1 10 100

X(h

) (g

/cm

2)

Ë

h (km)

Figure 2.4.Vertical atmosphericdepth,Ì ¦ , versusvertical altitudeover sealevel, ¬ , accordinglywith Linsley’s model[16].

For the samereason,the chemicalcompositionof the air canbe assumedto be constantin thefull rangeof non-vanishingdensity( p/��¬Í��¬ Ç�ÈÊÉ ). As shown in figure2.2,thisonly affect theveryupperlayerof theatmosphere,with altitudeslargerthan90 km.

A further approximationthat will be madewhennecessaryis to assumethat theair is a “pure”substancemadewith “air” atomswhosenucleipossesscharge Î�Ï¶Ð andmassnumberÑ«Ï¶Ð . To matchtheactualmolecularweight,it is necessaryto set Î�Ï¶ÐÒ|��2³´� and ÓÔÎ�Ï¶ÐFs�ÑÕÏ¶Ð×Ö�|ØpÙ³´Ã [1].

Thedensityof theair is not directly usedby the relatedalgorithms:Thequantitythatnaturallydescribesthevaryingdensityof theatmosphericmediumis thesocalledvertical atmosphericdepth,Ì ¦ , definedasfollows:

Ì ¦ ¢¶¬ ¥ | ÚÍÛ½ ©F¢ xN¥wÜ2x ³ (2.4)

Theintegrationpathis thevertical line thatgoesfrom thegivenaltitude, ¬ , up to infinity. Theusualunit to expressÌ ¦ is gs cmt . In figures2.4 and2.5, Ì ¦ ¢¶¬ ¥ (Linsley’s model) is plottedagainst¬ .Noticethat Ì ¦ ¢hp ¥�Ý op�p�p gs cmt and Ì ¦ ¢¶¬ ¥�Þ p for ¬ Þàß asexpected.


0.0001

0.001

0.01

0.1

1

10

100

10 100

X(h

) (g

/cm

2)

Ë

h (km)

Figure 2.5.Sameasfigure2.4,but for altitudeslargerthan10 km.

©F¢¶¬ ¥ canbeobtainedfrom Ì ¦ ¢¶¬ ¥ via

©w¢¶¬ ¥ |�á Ü Ì ¦ ¢¶¬ ¥Ü ¬ ³ (2.5)

Linsley’s parameterizationof Ì ¦ ¢¶¬ ¥ [16], is doneasfollows: (i) The atmosphereis divided inâlayers. For ãä|åo�£³³³H£ â layer ã starts(ends)at altitude ¬�æ ( ¬�æèç q ). It is clear that ¬ q |ép and¬�ê ç q |Ø¬ Ç�ÈÊÉ . (ii) Ì ¦ ¢¶¬ ¥ is givenby:

Ì ¦ ¢¶¬ ¥ |Åëìíìîï æN§ð�æa¹ º ½?¾ �Ôñ ¬�æ��¬Í��¬Áæòç q £ ãó|�o�£³³³?£ â áôoï êõáöð¼ê¨¢¶¬Ps�÷�ê ¥ ¬�êø��¬ù��¬�ê ç qp ¬ � ¬ ê ç q ³

(2.6)

Wherethecoefficients ï æ , ð�æ and ÷�æ , ãú|�o�£³³³?£ â areadjustedto fit thecorrespondingexperimentaldata.Thecoefficientsusedin AIRES2, which correspondto a modelwith

â |#Ã layers,arelistedintable2.1,andaretheonesthatcomeout from afit to theUSstandardatmospheredata.TheLinsley’smodelpredictionfor ©F¢¶¬ ¥ plottedin figure2.3 wasobtainedusingthis coefficient setandequations(2.6)and(2.5).

Anotherimportantpropertyof Linsley’s parameterizationis that Ì ¦ ¢¶¬ ¥ caneasilybeinvertedtoobtain ¬4|�Ì º q¦ ¢hÌ ¥ ( Ì � p ): Let Ì�æw|�Ì ¦ ¢¶¬Áæ ¥ , ã�|ûo�£³³³?£ â , then

¬ü| ëìíìîá«÷�æ�ýÿþ�� Ì�á ï æð�æ � Ì�æèç q ��Ì �ôÌ�æÔ£ ãó|�o�£³³³?£ â áôo÷�ê¨¢ ï ê4á;Ì ¥ s�ð�ê p��ôÌ �ôÌ�ê�£ (2.7)

2Thesecoefficientscorrespondto the default setting,andarecoincidentwith the onesusedin the programMOCCA[1]. In the currentversionof AIRES an alternative setof coefficientscorrespondingto a SouthPoleatmosphereis alsoavailable.


Layer Layer limits (km) ï æ ð�æ ÷�æã From To (gs cmt ) (gs cmt ) (m)1 0 4 á 186.5562 1222.6562 9941.86382 4 10 á 94.9199 1144.9069 8781.53553 10 40 0.61289 1305.5948 6361.43044 40 100 0.0 540.1778 7721.70165 100 � 113 0.01128292 1 op��

Table2.1. Linsley’s modelcoefficientsfor theUSstandard atmosphere [16]. Thenumberof layers isâ |ØÃ .wherethereplacementÌ ¦ ¢¶¬Áê ç q ¥ |�p hasbeenmade.

A quantityrelatedto the vertical depththat appearsfrequentlyin air shower calculationsis theslantatmosphericdepth, Ì�� , definedsimilarly as Ì ¦ (equation(2.4)) but usinga non-vertical inte-grationpath. In mostapplicationstheintegrationpathis a straightline goingalongtheshower axis,from thegivenpoint to infinity. In this caseÌ � takestheform:

Ì��H¢ xN¥ | Ú�¤Û ©w¢ x�¦�¥wÜ ãÊ£ (2.8)

wheretheprimein theintegral indicatesthatthepathis alonganon-verticalline and x ¦ is theverticalaltitudedefinedin equation(2.1).

The integral in equation(2.8) cannotbe solved analytically in the generalcaseof an arbitrarygeometry(seepage214). If theEarth’s curvatureis not taken into account(planeEarth),thenit isstraightforwardto prove that

Ì��H¢¶¬ ¥ | Ì ¦ ¢¶¬ ¥� �� £ (2.9)

where � is thezenithangleof theshower axis (seesection2.1.1). Fromthis equationit comesoutthat Ì�� dependsnotonly on ¬ but alsoon � andthelocationof thegroundsurface.

Unlessotherwisespecified,any referenceto atmosphericdepth,or depth, is assumedto be areferenceto Ì ¦ whichmayalsobenotedsimply Ì .3

2.1.3 The slant depth and the Earth’s cur vature .

Many air shower observables,especiallythe groundlevel distributions,dependon the thicknessoftheair layerthatseparatesthestartingpoint of anair shower from thegroundlevel. For non-verticalshowersstartingat the top of theatmosphere,this thicknessis measuredin termsof theslantdepthevaluatedat groundlevel, Ì � ¢ x � ¥ . TheplaneEarthapproximationgivenby equation(2.9) is usuallyemployed to evaluatethatquantity. However, this approximateequationcangive inaccurateestima-tionsfor largezenithangles,andin factit is divergentfor ��|��p�� .

3Noticethatin somepublicationsthesymbol � is usedto representtheslantdepth.


Zenith angle CurvedEarth PlaneEarth

(deg) length (km) path (gs cmt ) length (km) path (gs cmt )0 110 1036.1 110 1036.1

30 127 1195.9 127 1196.445 154 1463.6 156 1465.360 215 2065.1 220 2072.270 303 3003.7 322 3029.480 518 5765.5 633 5966.785 757 10571.7 1262 11887.989 1083 25919.3 6303 59367.290 1189 36479.9 ß ß

Table2.2. Total showeraxislength( � ) andslantpath(gs cmt ) measuredfromthetopof theatmosphere (110km.a.s.l)downto sealevel, tabulatedversusthezenithangle.

To preciselyestimateÌ��?¢ x��¥ we have evaluatednumericallythe integral of equation(2.8) forvariousrepresentative cases.In table2.2 the resultscorrespondingto x�� | p (groundlevel locatedat sealevel) are tabulatedfor different zenith angles. The top of the atmosphereis locatedat analtitudeof 110 km.a.s.l,andLinsley’s parameterizationis usedin the calculations.The respectivedatacorrespondingto theplaneEarthmodelarealsotabulatedfor comparisonpurposes.

The tabulatedquantitiesindicatethat the planeandcurved Earthestimationsdiffer in lessthan4% for all zenithangles� �"²�p�� , andthe differencesincreasenotablyaslong asthe zenithangleapproaches��p�� .

Thegeometricallengthof theshoweraxis, ï , is alsotabulatedfor bothmodels.In theplaneEarthapproximationthis lengthis givenby ï | x Ç�ÈÊÉ á x�� £ (2.10)

wherex Ç�ÈÊÉ is the(vertical)altitudeof thetopof theatmosphere(110km in thepresentcase).On theotherhand,if theEarth’s curvatureis takeninto account,theexpressionfor ï becomes

ï |�� ¢hy{z¨§ x�¦ Ç�ÈÊÉ ¥ t á�¢hy{z¨§ x��¥ t �� þ t �Øá�¢hy{z¨§ x��¥ � �� ä£ (2.11)

where x�¦ Ç�ÈÊÉ standsfor the vertical altitudeof the injection point (110 km). Equation(2.10) is they{z Þàß limit of equation(2.11).

2.1.4 Range of validity of the “plane Earth” appr oximation

In section2.1.1(page11) it is specifiedthatthelimit of the“planeEarth” zoneis locatedat acertaindistancefrom thecentral x -axis.Thisdistancevarieslinearlywith thealtitudeandgoesfrom 4 km atsealevel up to 22.5km at 100km above sealevel.


To determinethe boundariesof that zone,that is, a region whereplanegeometrycansafelybeusedin the involved procedures,the requirementof expressingthe vertical depthof a given pointwith enoughprecisionwastakeninto account.Theconditionactuallyimposedcanbedefinedin thefollowing terms:Let Ü bethehorizontaldistanceof a certainpoint to the x -axis,andlet x and x¦ bethepoint’s centralandverticalaltitudes.Let� Ìö¢ Ü,¥ |·Ì ¦ ¢ x ¦ ¥ á Ì ¦ ¢ xN¥ ³ (2.12)

In a planegeometry,� Ì is zero for all Ü provided x is kept fixed. We can usethis quantity to

determinea safe“planezone” imposinga boundon� Ì . After a seriesof technicalconsiderations,

too many to beexplainedin detailhere,we concludedthat thegeometrycanbeacceptablytakenasplanefor all pointswhosedistancesto the x -axisarelessthan Ü Ç�ÈÊÉ definedby thecondition4:� Ìª¢ Ü Ç�ÈÊÉ ¥ ��pÙ³´°�Ã gs cmt �� ° � Ìö¢ Ü Ç�ÈÊÉ ¥ ��o % �ùÌ ¦ ¢ xN¥ ³ (2.13)

Usingequations(2.1)and(2.13),andtakinginto accountthat� Ì �| ¢ x�¦ á xN¥ ©F¢ xN¥ , it is simpleto

obtainestimationsfor Ü Ç�ÈÊÉ at differentaltitudes.At sealevel, for example,wheretheverticaldepthis approximately1030gs cmt , andthedensityof theair is 1.22 ��Ns��/Ä , weobtain

Ü Ç�ÈÊÉ! �öÃN³´Ã"�#�4³ (2.14)

Thesamecalculationfor 100km above sealevel yields

Ü Ç�ÈÊÉ �=°j�$�#�ü³ (2.15)

Theboundariesof usedby AIRES(seesection2.1.1)agreewith theseresults.

2.1.5 Geomagnetic field

All chargedparticlesthatmoveneartheEartharedeflectedby thegeomagneticfield. Suchdeflectionsaretakeninto accountin theinternalalgorithmsof AIRES.

TheEarth’s magneticfield, % , is describedby its strength,F, &ö|(')%�' ; its inclination,I, definedasthe anglebetweenthe local horizontalplaneandthe field vector;andits declination,D, definedas the anglebetweenthe horizontalcomponentof % , H, and the geographicalNorth (directionofthe local meridian). TheangleI is positive when % pointsdownwardsandD is positive whenH isinclinedtowardstheEast.

Let ¢+*-,Ù£�*-.l£�* ¥ betheCartesiancomponentsof % with respectto theAIREScoordinatesystem(section2.1.1).They canbeobtainedfrom thefield’s strengthandinclinationvia*-, |0/ � ��21 £ *-. |�pÙ£ * |±á3/ �)� þ 1 ³ (2.16)

4This requirementis morestringentthat theoneusedfor AIRES version1.4.2aor earlier. Theoriginal equations[12]werenotadequatein certainparticularconditions,namely, quasi-horizontalshowers,andwerethusmodified.


*-. is alwayszeroby construction,sincein theAIREScoordinatesystemthe u -axispointsto thelocalmagneticnorth,definedasthedirectionof theH componentof thegeomagneticfield.

Therearetwo alternativesfor specifyingthegeomagneticfield in AIRES: (i) Manually, enteringF, I andD. (ii) Giving thegeographicalcoordinates,altitudeanddateof a given event. In the latercase,themagneticfield is evaluatedusingtheInternationalGeomagneticReferenceField(IGRF)[8],awidely usedmodelbasedonexperimentaldatathatgivesaccurateestimationsof all thecomponentsof theEarth’s magneticfield.

Wearenotgoingtoplacehereany furtheranalysisof thegeomagneticfieldandits implementationin anair showersimulationprogram.Theinterestedreadercanconsultreference[17] whichcontainsa detaileddescriptionof generalaspectsof the geomagneticfield and the IGRF, togetherwith adiscussionaboutthepracticalimplementationof thedeflectionprocedureandananalysisof theeffectof thegeomagneticfield onseveralair shower observables.

2.2 Air sho wers and par tic le physics

We aregoing to describeherehow the particlesof an air shower are identifiedandprocessedandwhich interactionsaretakeninto account.

2.2.1 Partic le codes.

AIRES recognizesall theparticlescommonlytaken into accountin air shower simulationsplusad-ditional onesincludedfor completeness.Eachparticleis internally identifiedby a particlecode. Itis importantto notice,however, thatuserlevel particlespecificationsaremadeby meansof particlenamesinsteadof numericcodes.

Table2.3 lists AIRES particlecodes,togetherwith the correspondingparticlenamesandsyn-onyms.

Nuclearcodesaresettakinginto accountÎ (atomicnumber),4 (numberof neutrons)and Ñ�|ÎÆ§54 (massnumber),in acomputationallyconvenientcodificationformula:

code |�op�pÕ§��°�Î§Ø¢+4 á=ÎÆ§² ¥ £ (2.17)

with pü�64 áÆÎ§²õ��Ùo . Taking oä�ØÎ��Ø°�~ (from hydrogento iron), this codingsystemallowsto uniquelyidentify all known isotopes.

Regardingthenamesof nuclei,they canbespecifiedin severalways:(i) By theirchemicalnames,for exampleFeˆ56(56 refersto themassnumber Ñ , which defaultsto the mostabundantisotope’smassnumberwhennot specified).(ii) By specialnames,asDeuterium for H t or Ir on for Fe798 . (iii)By directspecificationof Î , 4 and/orÑ , for exampleNZ 2 2 (He: ), ZA 26 54 (Fe7 : ), etc.

In certaincasesit maybeneededto refertogroupsof particleshaving somepropertiesin common.Thereareseveralparticlegroupsdefinedin theAIRESsystemwhichcanbeusefulin suchsituations.Themostimportantgroupsof particlesarelistedin table2.4.


Particle Code Nameandsynonyms; 1 Gammagamma¹ ç 2 e§ Positron positron¹ º á 2 eá Electron electron< ç 3 mu§ Muon§ muon§< º á 3 muá Muoná muoná= ç 4 tau§= º á 4 tauá> z 6 nu(e)?> z á 6 nubar(e)>A@ 7 nu(m)?>A@ á 7 nubar(m)>AB 8 nu(t)?>AB á 8 nubar(t)C ¸ 10 pi0C ç 11 pi §C º á 11 pi áD ¸E 12 K0SD ¸ê 13 K0LD ç 14 K §D º á 14 K áF 15 etaG20 lambda?G á 20 lambdabH 30 n Neutron neutron?H á 30 nbar AntiNeutron antineutronI 31 p Proton proton?I á 31 pbar AntiProton antiproton

Table2.3. AIRESparticlecodesandnames.Thenuclearcodingsystemandnuclearnamesareexplainedin thetext.


Groupnameandsynonyms Particlesin thegroup

NoParticles None EmptygroupAllParticles All Universalgroupcontainingall particlesAllCharged All chargedparticles,includingall nucleiMassiveNeutral All non-chargedmassive particlesNuclei All nucleiHadrons All hadronsNeutrinos All neutrinosandanti-neutrinosEM ; £ ¹ ç £ ¹ ºe§}á ¹ ç £ú¹ ºmu§}á < ç £ < ºtau§}á = ç £ = ºGPion C ç £ C º £ C ¸GChPion C ç £ C ºGKaon

D ç £ D º £ D ¸E £ D ¸êGChKaon

D ç £ D ºnppbar H £ I £ ?Innbar H £ ?HNucnucbr H £ ?H £ I £ ?I

Table2.4.AIRESparticle groups.

2.2.2 Interactions taken into account in the current version of AIRES

Theprocesseswhich aremostrelevant from theprobabilisticpoint of view aretakeninto accountinAIRES.In thecurrentversion(2.6.0),thefollowing interactionsareincluded:5J Electrodynamical processes:

– Pair productionand ¹ ç ¹ º annihilation.

– Bremsstrahlung(electronsandpositrons).

– Muonbremsstrahlungandmuonicpairproduction[18].

– Emissionof “knock-on” electrons( K rays).

– Comptonandphotoelectriceffects.

– LPM effectanddielectricsuppression.6

5Thesetof consideredprocessesis similar to thecorrespondingonefrom theMOCCA simulationprogram[1], but inmostcasesthealgorithmshave beenimprovedanddebugged.

6Thealgorithmscorrespondingto theLPM effect anddielectricsuppressionwerecompletelyrewritten for AIRES ver-sion1.4.2,andemulateMigdal’s theory[19]. Theproceduresincludedin previous versionsof AIRES, namely1.2.0and1.4.0,arenumericallyincorrectleadingto an“excessive” suppressioneffect which affectstheresultsof thesimulationsincertaincircumstances[20]. Thisbug is presentalsoin MOCCA’sLPM procedures,asreportedby D. Heck[21]. Addition-ally, thepreviousalgorithmsdonot take into accounttheeffect of thedielectricsuppression.

CHAPTER 2. GENERAL CHARACTERISTICS OF AIRES 23J Hadronic processes:

– Inelasticcollisionshadron-nucleus.

– Photonuclearreactions.

– Nuclearfragmentation,elasticandinelastic.J Unstableparticle decays.J Particle propagation:

– Mediumenergy losses(ionization).

– Coulombandmultiple scattering.

The hadronicinelasticcollisions andphotonuclearreactionsareprocessedby meansof exter-nal hadronicinteractionmodelswhentheir energy is above a certainthreshold;otherwisethey arecalculatedusinganextensionof Hillas’ splitting algorithm[4, 22].

AIRES includes(optionally) links to two well-known external hadronicinteractionpackages,namely, SIBYLL [6] andQGSJET[7].

2.2.3 Processing the interactions

Wearegoingto briefly describehow thedifferentinteractionsareprocessedin AIRES.Weshallfocusin thecomputationalaspectsof theseprocedures;a moredetaileddescriptionof thephysicsinvolvedin suchprocessesis goingto bepublishedelsewhere[23].

Most of theproceduresheredescribedarepartof thegroupof physicalalgorithmsalreadyintro-duced,andvirtually all of themareimplementedequivalentlyasin thesimulationprogramMOCCA[1].

Firstof all it is necessaryto expressthatthisdescriptionis ageneralone:Theactualalgorithmsdoincludea numberof technicaldetailswhosecompleteexplanationis beyondthescopeof this work,evenif theirphilosophyis concordantwith theschemeherepresented.

As mentionedbelow, in AIRES theparticlesarestoredin arrays(stacks)andprocessedsequen-tially. Eachparticleentryconsistsof differentdataitemscontainingthedifferentvariablesthatchar-acterizeit: Particlecode,energy, position,directionof motion,etc.

For thesimulationengine,theshower startswhentheprimaryparticleis addedto thepreviouslyemptystack.Thenthestackprocessingloopbegins.

Let L , ¡ , M , N berespectively thekineticenergy, position,timeanddirectionof motionof agivenparticleidentifiedby its particlecode OQP . Whenthis particle is going to be processedit will sufferoneof severalpossibleinteractionsR � , S | o�£³³³H£ H , H� o . To fix ideas,let usconsiderthecaseofapositron.Thepossibleinteractions,R � , are:annihilation,interactionwith anatomfrom themediumandemissionof a “knock-on” electron,andemissionof abremsstrahlungphoton.


Evaluating the mean free paths

Every interactionR � is characterizedby its crosssection,T � , or, equivalently, by its meanfreepath,U � . U � and T � areconnectedvia: U � |WV ÈYX[ZT � £ (2.18)

where V ÈYX[Z is themassof anatomof themediumtheparticlepropagatestrough,that is, anaverageatomof “air” in thecaseof air showers.Theusualunitsfor

U � aregs cmt .Themeanfreepathsdo dependon thekind of interactionandon theparticle’s instantaneouspa-

rameters.They canbe calculatedanalytically for certaininteractions;in othercasesthey mustbeestimatedby meansof parameterizationof experimentaldata,andthis generallyrequiresextrapola-tionsout of theregion correspondingto themeasurements.A typical exampleof this situationis thecaseof themeanfreepathsfor inelasticcollisionsparticle-nucleus,where“particle” canbeproton,gamma,othernucleus,etc.Suchmeanfreepathsdependon theenergy of theprojectileparticle,andmustbecalculatedfor energieswell above themaximumenergiesattainablein collider experiments.

Figure2.6 containsplotsof themeanfreepathscorrespondingto proton-nucleus,pion-nucleus,kaon-nucleusandFe-nucleuscollisions,plottedasa functionof theprojectileenergy. All thealterna-tivesetsof meanfreepathsavailablein AIRES aredisplayed.

Selecting the par tic le’s fate

For eachinteractionS , U � representsthemeanpath(expressedin “quantityof matter”,thatis, gs cmt )the particleshouldmove beforeactuallysuffering the interaction. To evaluatethe actualpathto agiven interaction,it is necessaryto samplethe correspondingexponentialprobability distribution,\ � ¢ IP� ¥ | U º q�^] _#` ¢ á I�� s U � ¥ . Let I�� , Sø| o�£³³³H£ H the set of valuesobtainedafter samplingthecorrespondingdistributionsfor all thepossibleinteractions.

The interactionthe particle will actually undergo, also called the fate of the particle, is thenselected:It is theinteractiona correspondingto theminimumof the I�� ’s, thatis, Icb � IP� for all S .Moving the par tic le and processing the selected interaction

After theparticle’s fatehasbeendecided,thecorrespondinginteractionbeginsto beprocessed.First,theparticlemustbeadvancedthepathindicatedby Icb . It is necessaryto convert thepathin ageomet-rical distance,andthis dependson theatmosphericmodelandtheparticle’s currentposition. In thecaseof chargedparticles,theadvancingprocedurealsotakescareof theionizationenergy losses,thescatteringandthegeomagneticfield deflection.During this step,theparticle’s coordinates,directionof motionandenergy canbealtered.

Thefinal stepis to processtheinteractionitself. This generallyinvolvesthecreationof new par-ticles(secondaries)whichareaddedto thecorrespondingstacksandremainwaiting to beprocessed,andeventuallythedeletionof thecurrentparticle,for examplein thecaseof positronannihilation.

In somecases,it is necessarytoapplycorrectionsto theprobabilitydistributionsusedtodeterminethe particle’s fate. This happenswith processeswhich have rapidly changingcrosssections,or by


30d40e50f60g70

80h90i

104

106j

108

1010

1012

Lab. energy [GeVk

]

MF

P [g

/cm

2 ]

Protonl

20m30d40e50f60g70

80h90i100

110120

104

106j

108n

1010

1012

Lab. energy [GeVk

]

MF

P [g

/cm

2 ]

Pionl

40

60g80h100

120

140

104

106j

108

1010

1012

Lab. energy [GeVk

]

MF

P [g

/cm

2 ]

Kaon

8h9i

10

11

12

13

14

105

107

109o

1011

Nucleus energy p

[GeVk

]

MF

P [g

/cm

2 ]

Iron

Figure 2.6.Hadronic meanfreepathsversusprojectileenergy (lab system).Thesolid (blue),anddashed(red)linesrepresent,respectivelytheSIBYLL2.1andQGSJET01models.In theproton,pionandkaoncasesthemeanfreepathscorrespondingto themodelsSIBYLL1.6(dot-dashed,green)andQGSJET99(dotted,cyan)havebeenincludedfor comparison.Theiron plot includesalsothemeanfreepathsevaluatedusingtheAIRESbuilt-in algorithmin theSIBYLL(dot-dashed,green)andQGSJET(dotted,cyan)cases.


corrective processesnot taken into accountin the original selection7. The result of the correctiveactionis thatof cancelingsomeinteractions.In suchcasestheparticleis left unchangedandremainsin thestackfor furtherprocessing.

Partic les arriving to destination

The mechanismso far describedis capableof generatingandpropagatingall the secondariesthatcomeafter the first interactionof the primary particle. To let the shower finish it is necessarytodeterminewhena particleshouldno morebe tracked. In AIRES this correspondsto thecasewhenoneor moreof thefollowing conditionshold:q Theparticle’s energy is below agiventhreshold(low energy particles)8.q Theparticle’s positionis outof theinterestingregion (lostparticles).q Theparticlereachedthegroundlevel.

It is very simpleto show that this is enoughto ensurethat thesimulationof a shower will endin afinite time.

Partic le monitoring

Thesimulationprogramsincludeseveralmonitoringroutinesthatconstantlycheckthestatusof theparticlesbeingpropagatedandaccumulatedatathenusedto evaluatethedifferentair shower observ-ables.

Theeventsthataremonitoredare:q Particlesthatreachgroundlevel.q Particlesthat passacrosspredeterminedobservinglevels. The observinglevels areconstantdepthsurfacesgenerallylocatedbetweenthe injection andgroundlevels, andseparatedby aconstantdepthincrementrtstu : If v!u is thenumberof observinglevels ( vwu�xzy ), and s|{~}��u( s�{��u ) is theverticaldepthof thefirst (last)observinglevel ( s|{~}��u � s�{��u ), thentheverticaldepthof theotherobservinglevelsis givenby

rtstu6� s|{��u � s�{�}��uv!u � ys {��u ��s {~}��u��+� � yA��r�stu�� y��vwuA� (2.19)

Noticethatthefirst observinglevel is thatof highestaltitude.

7TheLandau-Pomeranchuk-Migdal(LPM) effect [19, 24, 25] is anexampleof suchkind of processes.TheLPM effectimpliesareductionof thecrosssectionof �)��+� processesatveryhighenergies.In AIRESit is implementedasacorrectivealgorithmwhoseeffect is thatof rejectinga fractionof thepreviously “approved” processes.As a result,thecorrectcrosssectionsarestatisticallypreserved.

8Unstableparticlesareforcedto decays.

CHAPTER 2. GENERAL CHARACTERISTICS OF AIRES 27q Chargedparticlesthatmove acrosstheair. For suchparticlesthecontinuousenergy lossesbyionizationof themediumareevaluatedandrecorded.

Thedatacollectedby themonitoringroutinesareusedto evaluatedifferentkind of observables,for example:

Longitudinal developmentof the shower. Tabular datagiving the numberandenergy of particlescrossingeachdefinedobservinglevels.

Shower Maximum. Thedatacollectedfor thelongitudinaldevelopmentof all chargedparticlesareusedto estimatetheshowermaximum,s¡ £¢�¤ , that is, theverticaldepthof thepoint wherethenumberof chargedparticlesreachesits maximum(seesection4.1.1).

Lateral distributions. Frequency distributions recordingthe numberof particlesreachingground,asa functionof theirdistanceto theshower core.

Energy distributions. Energy spectraof thedifferentparticlesat groundlevel.

Arri val time distributions. Meangroundlevel arrival time of differentparticlekindsasa functionof theirdistanceto theshower core.

All theoutputcomingfrom themonitoringroutinesis savedin theform of datatablesthatcanbeeasilyretrievedby theuser(seechapter4).

2.2.4 Random number generator

AIRES containsmany proceduresthat requireusingrandomnumbers,themost importantexamplebeingthe propagatingproceduresthat weredescribedin theprecedingparagraphs.Thosenumbersareadequatelygeneratedby meansof a built-in pseudorandomnumbergenerator[1], whosesourcecodeis includedwithin theAIRES distribution.

During theearlystepsof AIRES development,the randomnumbergeneratorwaschecked witha seriesof tests,includinguniformity andcorrelationtestsamongothers.In particular, this pseudo-randomnumbergeneratorpassedthe very stringent“randomwalk” and“block” testsdescribedinreference[26].

A moredetaileddescriptionof the different routinesassociatedwith the generationof randomnumberscanbefoundin appendixD (page144).

2.3 Statistical sampling of par tic les: The thinning algorithm

Thenumberof particlesthatareproducedin anair showergrowssignificantlywhentheenergy of theprimary increases.For ultra high energy primariesthatnumbercanbe large enoughto make it im-possibleto propagateall thesecondariesevenif themostpowerful computerscurrentlyavailableareused.Thetotalnumberof particlesin ashower initiatedby a y�¥§¦9¨ eV protonprimaryis approximatelyy�¥ }9} , beingalmostimpossibleevento storethenecessarydatafor suchanamountof particles.


The simulationsaremadepossiblethanksto a statisticalsamplingmechanismwhich allows topropagateonly asmallrepresentative fractionof thetotal numberof particles.Statisticalweightsareassignedto thesampledparticlesin orderto compensatefor the rejectedones.At thebeginning ofthesimulation,theshower primaryis assignedaweight1.

At the momentof evaluatingaveragesto obtainthe physicalobservables,eachparticleentry isweightedwith the correspondingstatisticalweight. For example,the observablescomingfrom themonitoringroutines,listedin section2.2.3,areevaluatedtakinginto accountthosestatisticalweights.Ontheotherhand,unweighteddistributionsaresimultaneouslycalculatedin thecasesof longitudinal,lateralandenergy distributions.They areusefulto monitorthebehavior of thesamplingalgorithm.

Thesamplingalgorithmusedin AIRES is calledthinningalgorithmor simply thinning. It is anextensionof thethinningalgorithmoriginally introducedby A. M. Hillas [4, 1], andwasimplementedmodularlyasa procedurewhich is independentof theunitswhich managethephysicalinteractions.The original Hillas algorithmandthe AIRES extendedthinning algorithmaredescribedin the fol-lowing sections.

2.3.1 Hillas thinning algorithm

Let usconsidertheprocess ©�ª¬« } « ¦ �� «- � ®�¯°y (2.20)

wherea “primary” particle

©generatesa set of ® secondaries

« } ��Q� «- . Let ±³² ( ±³´¶µ ) be theenergy of

©(

« � ), andlet ±¸·º¹ beafixedenergy calledthinningenergy.

Beforeincorporatingthesecondariesto thesimulatingprocesses,theenergy ±»² is comparedwith±3·�¹ , andthen:q If ±³²¼¯½±3·�¹ , every secondaryis analyzedseparately, andacceptedwith probability9

¾ � �À¿ÁÁÂ ÁÁÃy if ±-´2µÄ¯½±¸·º¹± ´¶µ±3·�¹ if ±-´2µ � ±¸·º¹ (2.21)

q If ±³² � ±¸·º¹ , that necessarilymeansthat the “primary” comesfrom a previous thinning op-eration. In this caseonly one of the ® secondariesis conserved. It is selectedamongall thesecondarieswith probability ¾ � � ±-´2µÅ Æ�Ç } ±³´cÈ � (2.22)

This meansthat oncethe thinning energy is reached,the numberof particlesis no morein-creased.

9Theprocedureactuallyusedin AIRES implementsthis stepin a technicallydifferentway, but retrieving statisticallyequivalentresults.


In bothcasestheweightof theacceptedsecondaryparticlesis equalto theweightof particle

©multipliedby theinverseof

¾ � .Thefactthatthestatisticalweightsaresetwith theinverseof theacceptanceprobabilitiesensures

anunbiasedsampling,that is, all theaveragesevaluatedusingtheweightedparticleswill not dependon the thinning energy, andwill be identical to the “exact” onesobtainedfor ±¸·�¹5�^¥ . Only thefluctuationsareaffectedby thethinninglevel: If ±¸·º¹ is closeto theprimaryenergy, thenthethinningprocessbegins early in the shower development,and a low numberof samplesis obtained,withrelatively large and fluctuatingweights. On the other hand, low thinning energies lead to largersampleswith lessstatisticalfluctuations.

Processinglargesamplesdemandsmorecomputertime,soloweringthethinninglevel makesthesimulationmoreexpensive from thecomputationalpoint of view.

2.3.2 AIRES extended thinning algorithm

Thethinningalgorithmof AIRES(2.6.0)includesanadditionalfeaturewhichhasprovedto behelpfulto diminish statisticalweight fluctuationsin many cases.This extendedalgorithmwasdesignedtoensurethatall thestatisticalweightsarenever largerthatacertainpositive numberÉËÊ"x�y , specifiedasanexternalparameter.

Themechanicsof theAIRES extendedalgorithmcanbesummarizedasfollows: Let Ì¸² betheweight of particle

©, and ÉËÍ � ÉËÊÏÎ�Ð be an additional(internal)positive number. Considerthe

numberof secondariesin theprocess(2.20).q If ®�ÑÓÒ then

– If Ì¸²5x�ÉËÍ or Ì¸²w±³²ÔÎÖÕØ×�Ù � ±³´ÛÚ ��±³´¶Ü#��x0ÉËÊ thenall thesecondaries

« } ��Q� «-arekept.

– OtherwisethestandardHillas algorithmis used.q If ®ÝxÞÒ then the standard Hillas algorithm is alwaysused,but if the weight of the singleselectedsecondary, Ì3´ , happensto belargerthan ÉËÊ , then ß copiesof thesecondaryarekeptfor further propagation,eachonewith weight Ì»à´ �áÌ3´ÄÎAß . The integer ß is adjustedtoensurethat ÉâÍ � Ì à´ � ÉËÊ .

In theAIRES algorithm ÉËÍã�°ÉËÊÏÎ�ä andthelimit ÉËÊ is definedviaÉËÊ¸� © ¨ ±3·�¹ÄÉ�åc� (2.23)

where

© ¨ is a constantequalto 14 GeVæ } and É�å is anexternalparameterwhich canbecontrolledby theuserandthatwill bereferredasthestatisticalweightfactor.

In orderto optimizethesamplingalgorithm,it is advantageousto definedifferentweight limitsfor differentparticletypes.In AIREStwo weightfactorsaredefined,É {�çéè��å and É {�êë�å , respectively


usedwhenprocessingelectromagneticor heavy particles.ParameterÉì{�ê��å is specifiedindirectly, bymeansof theuser-controlledratio © çéê � Éì{�çéè��åÉì{�êë�å (2.24)

thatpermitsevaluating É {�êë�å from É {�çéè��å .

Noticealsothat ÉâÊ dependson theabsolutethinningenergy ±3·�¹ . Theconstant

© ¨ wasadjustedsothat

© ¨ ±3·�¹ givesapproximatelythepositionof themaximumof theall particlesweightdistribution(seebelow). If É�å ªîí

theextendedalgorithmreducesto thestandardHillas procedure.

It is a simpleexerciseto show that this extendedthinningalgorithmis unbiasedwhile ensuring(by construction)thatall theparticleweightsbesmallerthantheexternallyspecifiedmaximumvalueÉËÊ of equation(2.23).

It is worthwhilementioningthat this procedureis not equalto the thinningalgorithmof Kobal,Filipcic andZavrtanik [5], evenif bothalgorithmsdo usetheconceptof keepingboundedthestatis-tical weights.

2.3.3 How does the thinning affect the sim ulations?

Theeffect of thestandardthinningon differentobservablesevaluatedduring thesimulationscanbeseenin figures2.7-2.9. All thesesimulationsweredoneusingidentical initial conditions: y�¥ }ðï eVprotonshowerswith verticalincidence;andconsideringfour differentthinningenergies,namely,±3·�¹ñÎA±3ò óºô ��y�¥ æ2õ , y�¥ æ÷ö , y�¥ æ2ø and y�¥ æ¶ù . In all casestheweightlimiting mechanismwasdisabled.

Figure2.7(page31)correspondsto thelongitudinaldevelopmentof all thechargedparticles,thatis the total numberof chargedparticlescrossingthe differentobservinglevels, asa function of theobservinglevels’ verticaldepth.

The plots in this figure show clearly how the statisticalfluctuationsdiminish systematicallyaslong asthethinningenergy is lowered.Comparetheplot for y�¥ æ2õ relative thinningwith thesmoothplotsobtainedfor thecasesy�¥ æ2ø and/or y�¥ æ¶ù . As mentioned,theCPUtime requiredincreaseseachtime the thinning energy is lowered. It is interestingto mentionthat the simulationsdoneat y�¥ æ¶ùthinninglevel requiredsome6300timesmoreCPUtimethantheonesdonewith y�¥ æ2õ thinninglevel.

Noticealsothatthemeanpositionsof thepointscorrespondingto any givendepthdonotpresentany evidentdependencewith thethinningenergy, asexpectedsincetheHillas thinningalgorithmisanunbiasedstatisticalsamplingtechnique.This observation appliesalsofor theplotsof figures2.8(page32)and2.9(page33).

Thedegreeof reductionof thefluctuationdoesdependontheobservableconsidered.In figure2.8(page32) the lateraldistribution of groundelectronsandpositronsis displayed,againfor differentthinning levels. It is noticeablethe degreeof persistenceof the noisy fluctuations,which arenotcompletelyeliminatedevenin the y�¥ æ¶ù relative thinningcase.

Thelateraldistribution of muonsdisplayedin figure2.9 (page33) reflectsanothercharacteristicof thethinningalgorithm.Evenif thefluctuationsarevery largefor y�¥cæ2õ relative thinninglevel, they


(a)

0

1e+10

2e+10

3e+10

4e+10

5e+10

0 200 400 600 8001000

No.

of P

artic

les

ú

X (g/cm2)

(b)

0

1e+10

2e+10

3e+10

4e+10

5e+10

0 200 400 600 8001000

No.

of P

artic

les

ú

X (g/cm2)

(c)

0

1e+10

2e+10

3e+10

4e+10

5e+10

0 200 400 600 8001000

No.

of P

artic

les

ú

X (g/cm2)

(d)

0

1e+10

2e+10

3e+10

4e+10

5e+10

0 200 400 600 8001000

No.

of P

artic

les

ú

X (g/cm2)

Figure 2.7.Effectof thethinningenergy on thefluctuationsof thenumberof chargedparticlescrossingthedifferentobservinglevelsduring theshowerdevelopment.Ten y�¥ }ðï eVverticalprotonshowers wereaveragedto obtainthedatafor each thinninglevel. Theplotslabeled(a), (b), (c), (d),correspondto ±¸·�¹ñÎA±»ò�óºô ��y�¥ æ2õ , y�¥ æ÷ö , y�¥ æ2ø and y�¥ æ¶ù , respectively.

reduceimmediatelywhenthethinningis lowered.Comparefor examplewith theplotsof figure2.7(page31). To understandthebehavior of thesedistributionsit is necessaryto recall that themuonsare very penetratingparticles,that is, they undergo a very reducednumberof interactionsbeforereachingground. Thereforetheir statisticalweightsremainsmall sincethey areproductsof a fewfactors,andthis fact is responsiblefor the low level of fluctuationsproduced.On the otherhand,groundelectronsandpositronsmostlikely comeout aftera long chainof processesinvolving manypredecessorparticles,andin suchcircumstancesvery large statisticalweightsareunavoidable,andhencethehigh level of fluctuationsobservedin the ûQüýûAæ distribution of figure2.8(page32).

The AIRES extendedthinning algorithmcanbe useful to reducesuchkind of fluctuations. Toillustratethispoint let usconsiderthesampleplotsdisplayedin figure2.10(page34).

The outstandingcharacteristicof theseplots is the fact that the densityfluctuationsdiminish


(a)0.1

1

10

100

1000

10000

100000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

(b)0.1

1

10

100

1000

10000

100000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

(c)0.1

1

10

100

1000

10000

100000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

(d)0.1

1

10

100

1000

10000

100000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

Figure 2.8.Effectof thethinningenergy on thefluctuationsof thelateral distribution of electronsandpositrons,in thesameconditionsasin figure 2.7.

whentheweightfactor( É {�çéè��å ��É {�ê��å ��É�å ) is lowered.In theparticularcasesof É|å¡�Ýy andÉ�åË�z¥ÿ�� the fluctuationscorrespondingto the y�¥cæ�� relative thinning areof the orderof the onescorrespondingto the y�¥cæ¶ù (Hillas algorithm)case(yellow band)which wereplottedin all casesforreference.

Lookingat thedistributionsof weightsdisplayedin figure2.11(page35), it is possibleto under-standtheactionof theweight limiting mechanism.Thedistributionslabeled“nl” (bluelines)corre-spondto the Hillas algorithmcase(no weight limits). Consideringthe the distributionsof weightsfor gammasasa typical case,it is evident that thereis a small fraction of particleshaving weightsup to threeordersof magnitudelarger thanthemostprobableones.This rarecasesaregenerallythecauseof many inconvenientsthatarisewhenanalyzingthedata.Theplotsfor finite É�å show clearlythat the distributionspresenta sharpend(correspondingto the valueof ÉËÊ ). In the caseÉ�åâ� ythegammadistribution endsapproximatelyat themaximumof the“nl” casecurve,asexpectedfrom


(a)0.1

1

10

100

1000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

(b)0.1

1

10

100

1000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

(c)0.1

1

10

100

1000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

(d)0.1

1

10

100

1000

50 100 1000

Den

sity

(P

artic

les/

m2)

þ

R (m)

Figure 2.9.Effectof thethinningenergy on thefluctuationsof thelateral distribution of muons,inthesameconditionsasin figure 2.7.

equation(2.23),wherethefactor

© ¨ is “tuned” to give ÉËÊ nearthedistribution’s maximumwhen É�åis equalto 1.

The muonweightsaregenerallysmallerthanthe electromagneticcounterparts(seethe discus-sion of figure 2.9 in page30). It is thereforenecessaryto usea smallerweight limit to modify thecorrespondingdistribution of weights. This is the caseof figure 2.11 that correspondsto the caseÉ {�ê��å � É {�çéè��å Î�ä§ä .

It is worthwhilementioningthattheweightdistributionscorrespondingto otherthinningenergieshave the sameshapeas the onesplotted in figure 2.11 (page35), but presenta global shift in theabscissasscalewhich is proportionalto thelogarithmof thethinninglevel (for example,theweightsfor the y�¥ æ2ø distribution areoneorderof magnitudelower thantheonesfor y�¥ æ�� andsoon).

Theimprovementin thelateraldistribution plotsis, of course,not free:TheCPUtimepershoweris increasedwhen É�å decreases.Figure2.12 (page35) representsthe CPU time consumptionper


10-4

10-3

10-2

10-1

1

10

10 2

10 3�10 4�

0�

1000 2000r (m)

ρ (m

-2)

no limit10

-4

10-3

10-2

10-1

1

10

10 2

10 3�10 4�

0�

1000 2000r (m)

ρ (m

-2)

w� f = 4010

-4

10-3

10-2

10-1

1

10

10 2

10 3�10 4�

0�

1000 2000r (m)

ρ (m

-2)

w� f = 20

10-4

10-3

10-2

10-1

1

10

10 2�10 3�10 4

0�

1000 2000

r (m)

ρ (m

-2)

w� f = 510

-4

10-3

10-2

10-1

1

10

10 2�10 3�10 4

0�

1000 2000

r (m)

ρ (m

-2)

w� f = 110

-4

10-3

10-2

10-1

1

10

10 2�10 3�10 4

0�

1000 2000

r (m)

ρ (m

-2)

w� f = 0.5

Figure 2.10.Effectof theAIRESextendedthinningon thefluctuationsof thelateral distribution ofelectronsandpositrons.Theplotscorrespondto y�¥ }ðï eVprotonshowers simulatedwith±3·�¹ñÎA± ò óºô ��y�¥cæ�� , anddifferentweightfactors ( É {�çéè��å �°É {�ê��å � É�å ). Theyellowbands( ) correspondto simulationsperformedin similar conditions,but usingtheHillas algorithmaty�¥ æ¶ù relativelevel. Thewidthof thebandscorrespondto theaverage valueplusandminusoneRMSerror of themean.

shower asa functionof É�å for variousthinningenergies.Thetime unit is theaveragetime requiredto completeashower simulatedwith y�¥ æ�� relative thinningand É|å ªîí

.

TheCPUtimepershower increasesmonotonicallywhen É�å decreases.Forany ±3·�¹ and É|å$��y ,for exampletherequiredtime is roughly5 timeslarger thantheonefor É|å ª í

. But it is 1.6 (13)timeslower thantheonecorrespondingto theHillas algorithmfor ±3·�¹ñÎcy�¥ ( ±¸·º¹ñÎcy�¥§¥ ). Thesefiguresmayrepresentanimportanttimesaving factorin certaincircumstances,for examplewhenevaluatinglateraldistributionslike theonesof figure2.10(page34).

Theuseof theAIRESextendedthinningalgorithmwith finite É�å is alwaysrecommended,how-


1

10

10 2

10 310 4

10 5�

0�

5

10log10 w

N o

f ent

ries

γ�

1

10

10 2

10 3

10 4

0�

5

10log10 w

N o

f ent

ries

e� +e� -

1

10

10 2

10 3

10 4

0�

2.5 5

7.5log10 w

N o

f ent

ries

µ+µ-

W�

f� = nl W

�f� = 5 W

�f� = 1 W

�f� = 0.2

Figure 2.11.Effectof theAIRESextendedthinningon thedistribution of weightsfor differentparticles(gammas,electronsandpositrons,andmuons).Theplotscorrespondto Ð��Ëy�¥ }ðï eVprotonshowers simulatedwith ±3·�¹ñÎA± ò óºô ��y�¥ æ�� , anddifferentweightfactors ( Éì{�çéè��å �°É|å ,É {�ê��å � É {�çéè��å Î�ä§ä ).

10-1

1

10

10 2

1 10 102

103�

10-5

10-6

10-7

10-4

wf�

CP

U ti

me

(arb

. uni

ts)

Figure 2.12.Processortimerequirementsfor theAIRESextendedthinningalgorithm,plottedversusÉ�å$�°É {�ç è��å �°É {�ê��å fordifferentrelativethinninglevels.All casescorrespondto y�¥ }ðï eVprotonshowers.


ever. Evenin theleastfavorablecases,it is possibleto getsmootherdistributionsfor everyobservablesettingÉ�å notlargerthan20andthuseliminatingtheparticleentrieswith unacceptablylargeweights.

2.4 Some typical results obtained with AIRES

Thelastsectionof thischapteris dedicatedto presentsomeillustrativeresultscomingfrom air showersimulationsmadewith AIRESusingtypical initial conditions.

Let usconsiderfirst thelongitudinaldevelopmentof showersstartedat thetopof theatmosphere.As mentionedin section1.1 (page5), the numberof particlesin a shower increasesinitially, thenreachesa maximum,andfinally theshower attenuatesasfar asanincreasingnumberof secondariesareproducedwith energies too low for further particlegeneration.This characteristicbehavior isillustratedin figure2.13which containsplotsof thelongitudinaldevelopmentfor all particles,gam-mas,electronsandpositrons,muons,pions,andkaons.Thedatausedin thisfigurecorrespondsto anaverageover 75vertical300EeV protonshowers.

Theplotsof figure2.13alsoshow usthatthegammasarethemostnumerousparticlescrossingtheobservinglevelsplacedneartheshower maximum.Theelectromagneticshower (gammas,electronsandpositrons)accountsnearlyfor all theparticlesin theshower. Noticethatnearthegroundlevel thenumberof muons,thenext mostnumerousparticles,is nearlytwo ordersof magnitudesmallerthanthe numberof electronsandpositrons10. The numberof groundpionsandkaonsareeven smaller,but at high altitudestheseparticlesrepresentanimportantfractionof all theparticlesof theshower;they canbeeven morenumerousthanthemuons.This is consistentwith the fact that thehadronicinteractions(producinglotsof secondarypionsandkaons)takeplaceat theearlystagesof theshowerdevelopment.

AIRES simulationenginealso recordsthe energy carriedby the different particlesthat crosseachobservinglevel. Theseenergy longitudinal developmentdataare plotted in figure 2.14, andcorrespondto thesamesetof showersusedfor thepreviousfigures.

The“all particles”plot givesthe total energy carriedby the tracked particlescrossingevery ob-servinglevel. Sinceneutrinosare not tracked, their energy is not included. At high altitude themediumenergy lossesarenot important,andthereforethe total energy carriedby the shower par-ticles remainconstant.But theavailableenergy begins to diminishaslong assuchlossesincrease;this eventbeingcorrelatedto thegrowth of theelectromagneticpartof theshower. In thecasebeingconsidered,the energy recoveredat groundlevel is about44% of the primary energy. This figureshouldbetakenonly asaqualitative measureof therecoveredenergy sinceit dependsstronglyontheinitial conditionsof thesimulation,for exampletheinclinationof theshower.

Thehadroniccharacterof theshoweratits beginningshowsupclearlywhenconsideringthepionsplot. At high altitude,the energy carriedby thepionsrepresenta large fraction of the total energy,thenthis energy reachesa maximumanddiminishesmonotonicallyaslong astheshower develops.

10The examplesherepresentedarejust to illustratesomegeneralaspectsof the air showers. The correspondingdataneednot accuratelyreproduceactualexperimentaldata. This observation appliesespeciallyto the numberof groundmuonswhichseemsto bestronglydependenton thehadronicmodelusedin thesimulations.


10 2

10 4

10 6�10 8�1010

1012

0 200 400 600�

800 1000

γ�e+e-

µ

π�K

All

X [g/cm2]�

N o

f par

ticle

s

Figure 2.13.Longitudinaldevelopmentof Ò��|y�¥§¦9¨ eVvertical protonshowers. Theerror barscorrespondto oneRMSerror of themeanandaregenerally smallerthat thesymbols.Theprimaryparticlesare injectedat thetopof theatmosphere, andthegroundis locatedat 300m.a.s.l.Thelongitudinaldevelopmentis recordedin 75 differentobservinglevels13 gÎ cm¦ apart. Theaveragepositionof theshowermaximumis s £¢�¤ � �� ¥ �c��"!#�c��yA� gÎ cm¦ .

10-6

10$ -5

10$ -4

10$ -3

10$ -2

10-1

1

0 200 400%

600�

800 1000$

γ�e+e-

µ

π�K

All

X [g/cm2]�

Ene

rgy

frac

tion

Figure 2.14.Energy longitudinaldevelopmentof Ò&� y�¥§¦9¨ eVverticalprotonshowers (theconditionsof thesimulationsareasdescribedin figure 2.13).


1e-02

1e-01

1e+00

1e+01

1e+02

1e+03

1e+04

1e+05

1e+06

100 1000

Par

ticle

den

sity

(1/

m2)

'

Distance to the core (m)

gammase+ e-

muonspions

np

Figure 2.15.Lateraldistribution of differentkindsof particlesreaching ground.Thedatacorrespondsto asingle y�¥ }ðï eVverticalprotonshowersimulatedwith y�¥ æ�(relativethinning.

Noticealsothebehavior of themuonenergy, which is negligible whentheshower startsbut growsconstantlyover-passingthepionenergy fractionnearthegroundlevel.

Another observablesnormally usedto describethe air showers are the lateral distributions ofgroundparticles,that is, the numberof particlesasa function of their distanceto the shower axis.In figure2.15thelateraldistribution of variousparticlekindsareplottedconsideringdistancesto thecorerangingbetween50 and2000meters.Theresultscorrespondto a singleshower simulatedwith)+* æ�, relative thinning . Thisvery low thinninglevel is responsiblefor thenoticeablesmoothnessofthedistributions,maintainedevenat largedistancesfrom thecore.

The basiccharacteristicsof the air shower lateraldistributionscanbe seenfrom this plot: Theelectromagneticcomponent,thatis,gammas,electronsandpositrons,is themostimportantin numberand,at thesametime, spreadswidely aroundthecorethat is thepoint of maximumparticledensity.In theotherextreme,thenucleoniccomponent,representedin figure2.15by theprotonandneutronlateraldistributionsconcentratesin a relatively narrow zonearoundthe shower axis. On the otherhand,evenif themuondensityis alwayssmallerthantheelectromagneticcounterpart,it diminishesmoreslowly with the distanceto the core,so the muon/electromagnetic ratio, resultsan increasingquantity.

The energy spectraof the particlesreachinggroundconstitutesalsoan importantobservable to


Figure 2.16.Sameasfigure2.15but for theenergy

distributionsof particlesreaching groundlevel.

1e+04

1e+05

1e+06

1e+07

1e+08

1e+09

1e+10

0.01 0.1 1 10 100 1000

dN/d

log(

E)

-

Energy (GeV)

gammase+ e-

muonspions

np

take into accountin theanalysisof air showers. In figure2.16suchdistributionsareplottedfor thesamey�¥ æ�( relative thinningsingleshower mentionedin theprecedingparagraphs.Theoutstandingfactrelatedto thesegraphsis thatthegammaand û ü û æ energy distribution have their maximumsformuchlowerenergiesthanthecorrespondingto themaximaof muons,pionsandnucleons.Therefore,even if theelectromagneticcomponentof theshower accountsfor theprincipal fractionsof particlenumberandenergy (seefigures2.13and2.14), the individual particlesarerelatively lessenergeticwhencomparedwith theaveragemuons,pionsandnucleons.

Anotherrelevantobservableto studyis thedistribution in timeof thedifferentparticlesthatarriveatgroundlevel. In figure2.17themeanarrival delaytime, . r&/10 , is plottedasa functionof thelateraldistance.Thearrival time delayfor eachparticleis thedifferencebetweentheabsolutearrival timeanda global time / ¨ definedasthe time requiredby light to go from the injectionpoint (the top oftheatmosphereis this example)to thegroundsurface,traveling alongtheshower axis. In a verticalshower all thedelaysarepositive. To obtaintheaveragevaluesplottedin figure2.17,all the timescorrespondingto particlesreachinggroundarounda certaindistance2 to theshower coreareaddedup anddividedby thecorrespondingnumberof particles.

Two well-known characteristicsof the time distribution can clearly be seenfrom the plots offigure2.17: (i) Themeantime delaysarelarger thantheonescorrespondingto asphericalfront with


03

500

1000

1500

2000

2500

3000

10$ 2

10$ 34

γ�e+e-

µ+µ-

distance from the core (m)5

<∆t>

(ns

)

Figure 2.17.Meanarrivaltimedistributionsfor y�¥ ¦9¨76 �eVvertical protonshowers.

centerat thefirst interactionpoint. (ii) In average,muonsarrivefirst, thenelectronsandpositronsandfinally gammas.

Non vertical showerspresentparticularcharacteristicsthat merit a separateanalysis. In figure2.18the lateraldistribution of gammas,electronsaremuonsarerepresentedas2D falsecolor plots(left column)andcontourcurvesplots(right column).Noticethatthedatacorrespondsto asingle30EeV inclinedprotonshower (zenithangle60 degrees)simulatedusingtheAIRES extendedthinningalgorithmwith a y�¥cæ�( thinning level and É�å �(Ð�¥ (in numberof processedentries,this is roughlyequivalentto a 89� ):* æ�; relative level Hillas thinningalgorithm). Theoutstandingcharacteristicoftheseplots if that the isondensitycurvesdo not possescylindric symmetry, andthusthecalculationof lateraldistributionsmustbedonewith specialcarewhentheshowersarenot vertical.

Inclinedshowerscanbealsosignificantlyaffectedby theeffect of theEarth’s magneticfield. Infigure2.19thepositive andnegative muondistributionsaredisplayedusing2D diagramssimilar tothoseof figure 2.18. Theartificially large field strengthusedfor this example(70 < T) helpsto putinto clearevidencetheeffect of thegeomagneticdeflections:The total < ü < æ distribution becomesbroader–in thedirectionof thenormalto theplanedeterminedby themagneticfield andtheshoweraxis–thanits counterpartfor the caseof no magneticfield. This effect alsoremainsevident whenprojectingthedistributionsontotheshower front plane.In thecaseof the lower plotsof figure2.19the projectionalgorithmtakes into accountthe shower attenuation.A detaileddescriptionof thatprocedureis beyondthescopeof this sectionandwill bepublishedelsewhere[27].

Usinga realisticmagneticfield of strength25 < T, thedeflectionsarelessevident,but not negli-gibleasillustratedin figure2.20.

Thecommentsherepresentedarenot intendedto bea completeanalysisof the influenceof the


-1000

0

1000

-1000 0 1000

10-1

1

10

10 2

10 3=10 4

xg> (m)

y g (m

)

γ-100

0

100

2 2.5 3?

3.5?

log(rg> ) (m)

φ - Φ

(de

g)

-1000

0

1000

-1000 0 1000

10-1

1

10

10 2@10 3=10 4A

xB g> (m)

yC g (m

)

e

-100

0

100

2D

2.5D

3?

3.5?

log(rE

g> ) (m)

φ - Φ

(de

g)

-1000

0

1000

-1000 0 1000

1

10

10 2@

xg> (m)

y g (m

)

µ-100

0

100

2 2.5 3?

3.5?

log(rg> ) (m)

φ - Φ

(de

g)

Figure 2.18.Lateral distributionsof muons,electronsandgammas,representedas2D falsecolorplots(left column)andcontourcurvesplots(right column).ThepositiveF -axisis directedtowardsthearrival direction.Thedatacorrespondsto a single Ò��|y�¥ }ðï eVprotonshowerwith a zenithangleof 70 degrees.Theenvironmentalparameters correspondto theEl Nihuil sitelocatedinArgentina(seetable3.2),andthesimulationsweredonewith a y�¥cæ�( thinninglevel and É�å$��Ð�¥ .


-1500

-1000

-500

0

500

1000

1500

-1000 0 100010

-1

1

10

xg> (m)

y g (m

)

-1500

-1000

-500

0

500

1000

1500

-1000 0 1000xg> (m)

y g (m

)

-1500

-1000

-500

0

500

1000

1500

-1000 0 100010

-1

1

10

x0G (m)

y 0 (m

)

µ-

-1500

-1000

-500

0

500

1000

1500

-1000 0 1000x0G (m)

y 0 (m

)

µ+

Figure 2.19.Lateral distributionsof positiveandnegativemuons,representedas2D falsecolorplots.Theuppergraphscorrespondto raw datarecordedat thegroundsurface, while theloweronesare projectionsontotheshowerfrontplaneusinga specialalgorithmthat takesinto accounttheshowerattenuation[27]. In theuppergraphsthepositiveF -axisis directedtowardsthearrivaldirection.Thearrowsrepresenttheprojectionof themagneticfieldontotheshowerfrontplane. Thedatacorrespondsto a single Ò��|y�¥ }ðï eVprotonshowerwith a zenithangleof 70 degrees.Theenvironmentalparameters correspondto theEl Nihuil sitelocatedin Argentina(seetable3.2),butusinganartificially large (70 < T) vertical magneticfield. Thesimulationswere donewith a y�¥ æ�(thinninglevel and É�å$��Ð�¥ .


-1500

-1000

-500

0

500

1000

1500

-1000 0 1000

1

10

10 2

xg> (m)

y g (m

)

-1500

-1000

-500

0

500

1000

1500

-1000 0 1000xg> (m)

y g (m

)

-1500

-1000

-500

0

500

1000

1500

-1000 0 1000

1

10

10 2

x0G (m)

y 0 (m

)

µ-

-1500

-1000

-500

0

500

1000

1500

-1000 0 1000x0G (m)

y 0 (m

)

µ+

Figure 2.20.Lateral distributionsof positiveandnegativemuons,representedas2D falsecolorplots.Theuppergraphscorrespondto raw datarecordedat thegroundsurface, while theloweronesare projectionsontotheshowerfrontplaneusinga specialalgorithmthat takesinto accounttheshowerattenuation[27]. In theuppergraphsthepositiveF -axisis directedtowardsthearrivaldirection.Thearrowsin theupper(lower)graphsrepresenttheprojectionof themagneticfield ontothegroundplane(showerfront plane).Thedatacorrespondsto a single Ò��|y�¥ }ðï eVprotonshowerwith a zenithangleof 60 degreesandrandomazimuth.Theenvironmentalparameters correspondtotheEl Nihuil sitelocatedin Argentina(seetable3.2),andthesimulationsweredonewith a y�¥ æ�(thinninglevel and É�å$��Ð�¥ .


geomagneticfield on air shower observables.The readerinterestedin a moredetailedstudyof thissubjectcanlook up in reference[17].

Chapter 3

Steering the sim ulations

Therearemany parametersthat mustbe specifiedbeforeandduring an air shower simulationjob.The Input DirectiveLanguage (IDL) is a partof theAIRES systemandconsistsin some70 human-readabledirectivesthatpermitanefficient controlof thesimulationsin acomfortableenvironment.

The mostcommonIDL directivesaredescribedin this chapter, andmany illustrative examplesarediscussed;a detaileddescriptionof the IDL languageis placedin appendixB (page114). It isrecommendedto properlyinstall thesoftware(seeappendixA) beforeproceedingwith thefollowingsections.

3.1 Tasks, processes and runs

Thesimulationof high energy air showersis a CPUintensive taskwhich candemanddaysandevenweeksof processortimeto complete.TheAIRESprogramwasdesignedtakingthisfactinto account:It includesan“auto-saving” mechanismto periodicallysave into an internal dumpfile (IDF) all rele-vantsimulationdata.In caseof asystemfailure,for example,thesimulationprocesscanberestartedat thepoint of thelastauto-saving operation,thusavoiding loosingall theprevioussimulationeffort.

The processingblock that goesbetweentwo consecutive auto-save operationsis calleda run.With taskwe meana specificsimulationjob, asdefinedby the input directives(for example,a taskcanbe“simulatetenprotonshowers”); andwith processwe identify a systemprocess,which startswhenAIRES is invokedandendswhencontrol is returnedto theoperatingsystem.

A taskcanbecompletedafteroneor moreprocesses,andtherecanbeoneor morerunswithin aprocess.Thelimit caseconsistsin having a taskfinishedin a singlerun (no auto-save) completedinasingleprocess(theprograminvokedjustonce).

3.2 The Input Directive Langua ge (IDL)

BoththemainsimulationprogramsAir esandAir esQ, andthesummaryprogramAir esSryreadtheirinput directives from the standardinput channel,andusea commonlanguageto receive the user’sinstructions.This languageis calledInput DirectiveLanguage (IDL).

45

46 CHAPTER 3. STEERING THE SIMULATIONS

TheIDL directivesarewrittenusingfreeformat,with onedirective perline (thereareno“contin-uationlines”, but eachline cancontainup to 176characters).Specialcharacterslike tabcharacters,for example,aretreatedasblankcharacters1.

All directivesarescanneduntil eitheranEnd directive or anendof file is found.Mostdirectivescanbeplacedin any orderwithin theinputstream.

IDL directives canbe classifiedasdynamicor static. Dynamicdirectives areprocessedeverytime theinputdatais scanned.Staticonescanbesetonly at thebeginningof a task:Any subsequentsettingwill not be taken into account.For instance,the maximumCPU time per run is controlledby a dynamicdirective (it canbechangedat thebeginningof every process,andis a parameterthatdoesnot affect the resultsof thesimulation);thegroundaltitude,instead,is an exampleof a staticparameterthatcannotbechangedduringthesimulations.

TheIDL sentencebeginswith thedirectivename.IDL is acasesensitive language,andin generaldirective namesmix capitalandlowercaseletters. The directivescanbe abbreviated. Considerforexamplethe following directive namePrimary Particle. You mustspecifytheunderlinedpart,andmayor maynotusetheremainingcharacters(Primary , PrimaryPart , PrimaryParticle referto thesameinstruction).

3.2.1 A fir st example

Therearefour directives that shouldbe alwaysspecifiedbeforestartinga simulationtask,namely,theonesthatcontrolthetaskname2, thestatementsthatprovide theprimaryparticletypeandenergyspecificationsandthedirective whichsetsthetotal numberof showersto besimulated.

Suchaminimalsetof specificationscanbeexpressedin termsof IDL directivesasfollows:

Task a first examplePrimary protonPrimaryEnergy 150 TeVTotalShowers 3End

Thesedirectives,like mostIDL directives,areself-explainingandpossesa simplesyntax.Theycanbeplacedin any order. Noticethattheparticlesarespecifiedby theirnamesandphysicalquanti-tieslike theenergy, for example,areenteredby meansof anumberplusaunit.

3.2.2 Errors and input checking

Every IDL directive is checked for correctsyntaxwhenit is readin. Additionally, someelementaltestsof the valuesgiven to the directive’s parametersare also made. When an error is detected,

1Specialcharacterswerenot supportedin AIRES1.2.0.2Actually, theTaskNamedirectiveis notmandatoryfor ataskto start,but its defaultvalueGIVE ME A NAME PLEASE

producesfile nameswhich areratherinconvenientto manage,andsoit is stronglyrecommendedto alwayssetthenameofa taskbeforeproceedingwith thesimulations.

CHAPTER 3. STEERING THE SIMULATIONS 47

a messageis written to the standardoutputchannel. Directives with errorsaregenerallyignored.Considerthefollowing directive:

PrimaryEnergy 100 MeV

If processedby AIRES, it will give thefollowing errormessage

EEEE

EEEE dd/Mmm/yyyy hh:mm:ss. Error message from commandparse

EEEE Numeric parameter(s) invalid or out of range.

EEEE >PrimaryEnergy 100 MeV<

EEEE

which indicatesthattheenergy specificationis outof range.3

AIRESdiagnosticmessagesalwaysincludeabrief explanationaboutthecircumstancesthatgen-eratedthe message,togetherwith the nameof the routinethat originatedit. The messagescanbeclassifiedin four categories,accordinglywith their severity: (i) Informativemessagesareusedtonotify theoccurrenceof certainevents,andaregenerallyassociatedwith successfullyconcludedop-erations.(ii) Warningmessages.Usedto put in evidencecertainnot completely“normal” situations.In general,processingcontinuesnormally. (iii) Error messagesindicateabnormaleventslike invalidinput directives,etc.,asillustratedin the previous example. (iv) Fatal messagesareissuedwhenaseriouserrortakesplace;in thiscasetheprogramstops.

The IDL instructionsetincludessomedirectivesthatallow checkinga given input dataset. Letusassumethat the input directivesaresaved into a file namedmyfile.inp. Let usconsideralsothatthis file containstheinstructionsof thefirst examplepreviously considered.

Theinstructionset:

TraceCheckOnlyInput myfile.inpEnd

if processedby AIRESwill generateanoutputsimilar to thefollowing:. . .0:0002 CheckOnly0:0003 Input myfile.inp1:0001 Task a first example1:0002 Primary proton1:0003 PrimaryEnergy 150 TeV1:0004 TotalShowers 31:0005 End0:0004 End. . .

3Theprimaryenergy mustbegreaterthan500MeV (seepage129).


TheCheckOnly directive instructsAIRES to normally readandcheckthe input data,andthenstopwithoutactuallystartingany simulations.Theinput linesplacedaftertheTracestatementareechoedto theterminal.andthe Input directivesallows includingIDL directivesplacedin otherfiles. Noticethe format usedfor directive echoing. It includesthe line numberaswell asthe file nestinglevel,startingby zerofor the standardinput channel.Input directivescanbe nestedandpermit splittingtheinputdatainto separatefiles. This is mostusefulfor organizingasetof inputfiles includingsomecommondirectivesin asinglesharedfile includedby every particularfile, etc.

In UNIX environmentsit is possibleto useoneof the scriptsof the AIRES RunnerSystemtoautomaticallycheckagiveninput file. For detailsseechapter5 (page101).

3.2.3 Obtaining online help

TheAIRES simulationand/orsummaryprogramsacceptinstructionsthatpermitobtaininginforma-tion aboutAIRESIDL instructions.Theinformationthatcanberetrievedin thisway is notextensivebut it canbeusefulto theexperienceduserasaquick guide.

Invoking AIRESinteractively andtyping“?” will returna list of thenamesof theIDL directives.“? * ” will causethe list to includealsothe hiddendirectives. The prompt“Air esIDL H ” typedattheterminalindicatesthatAIRES understandsthatthis sessionis interactive. TheHelp commandissimilarto ? but it will maintainpromptingdisabled.Duringaninteractivesessionit is alwayspossibleto enableor disablingthepromptby meansof thedirective Prompt.

Therearetwo otherkindsof helpthatcanbeobtainedusingthecurrentAIRES version,namely,“? tables” and“? sites”, whichdisplaythelist of availableoutputdatatables(seesection4.1and/orappendixC), andthecurrentlydefinedgeographicalsites(seesection3.3.4),respectively.

ThedirectiveExit , whichcanbeabbreviatedasx, will causeAIRESto stopimmediatelywithoutany further action–not even completingthe IDL instructionscanningphase–and is useful to endinteractive helpsessions.

3.2.4 Physical units

Therearemany IDL directiveswhich includeoneor morespecificationscorrespondingto physicalquantities. In mostcasesthesespecificationshave the format “number+ unit”, like in the Prima-ryEnergy specificationof section3.2.1,for instance.“Number” and“unit” arecharacterstrings,thefirst oneindicatesthe decimalnumericalvaluefor the quantitybeingspecified,while “unit” repre-sentsthe unit in which “number” is expressed.The charactersusedfor the unit field resemblethenameassignedin therealworld to thecorrespondingunit, e.g.TeV for Tera-electron-volt.

This featureof theIDL languagemakestheinput files morereadable,anddiminishesdrasticallythepossibilityof errorsin thespecifications,especiallyfor thosequantitieswhosevalidity rangesmayspanmany ordersof magnitude.In suchcasesanumberof commonlyusedmultiplesor sub-multiplesof thefundamentalunit aresurelyavailable.

Thecompletelist of unitscurrentlyimplementedis displayedin table3.1.


Magnitude Units Conversionfactors

Angle deg I degrad IKJMLONQP deg

Atmospheric depth g/cm2 I gN cmREnergy eV ISL+T�U GeV

keV ISL T�V GeVMeV ISL+T�W GeVGeV I GeVTeV ISLXW GeVPeV ISL V GeVEeV ISLXU GeVZeV ISL+Y R GeVYeV ISL Y[Z GeVJ \+]�^Q_a`bISLXU GeV

Length cm ISL+T R mm I mkm ISLXW min Lc]dL ^XeQ_ mft IK^ inyd f ftmi eX^XJML ft

Magnetic Field nT I nTuT ISL W nTmT ISLXV nTT ISL U nTuG ISL+TgY nTmG ISL R nTGs ISL Z nTgm I nT

Time ns ISL+T�U ssec I smin \ML shr fX\MLXL s

Table3.1. Physicalunitsacceptedwithin IDL directives.Theunderlinedkeywordsindicatetheunitsusedinternally to store thecorrespondingquantities.Themagneticfieldunit T (Gs) standsfor theSI(cgs)unit Tesla(Gauss),whilegm correspondsto h (1 hjikI nT).Timespecificationsusinghr, minand/orsec mayconsistin thecombinationof more thatonefield, like in 3 hr 30 min, forexample.


3.2.5 Carrying on

In figure3.1asecondexampleof anIDL inputdatasetis displayed.Noticefirst thatIDL instructionscanbecommented:All thecharactersfollowing a ‘#’ characterareignored.

TheSkip statementis alsousefulto placecommentsand/orintroduceplain text in theinput files(with noneedof singleline comment‘#’ characters),aswell asto skipapartof thedirectiveswithoutdeletingthelines.

Commentsandskippedlines arecompletelyignored:They just appearin the input file. Some-timesthis is not convenient,andit may be desirableto save their contentstogetherwith the outputgeneratedby thesimulatingprogram.TheRemark directive providesa meanto do this. Thestate-ment

Remark JUST AN EXAMPLE

placedin theexamplebeingdiscussed,instructsAIREStoplacethecomment‘JUSTAN EXAMPLE’togetherwith theoutputdata.Thereis no limit in thenumberof remarkinstructionsthatmayappearinsidea giveninput instructionset.TheRemark directive possessesanotheralternative syntax,veryusefulfor multi-line text:

Rem &eorThis is the first line of a multi-line remark.This is the second lineS p a c e s and TABS will be honored.. . .The label &eor marks the end of the remark.&eor

The directives that follow illustratea very useful featureif the IDL, which is the possibility ofdefiningglobalvariables. Suchvariablescanbeusedasreplacementtext within theIDL inputstream,and/orbepassedto outputfiles or externalmodulescalledby AIRES.Thevariablesmustbedefinedbeforethey canbeused.Thiscanbedoneby meansof theSetGlobaldirective. TheImport directivepermitsto import OS environmentvariables. Variablescan be overwritten, and deletedusing theDelGlobal directive.

The input datasetcontinueswith theTaskNameandthe threemandatorydirectivesalreadyin-troducedin section3.2.1.

Thedirectivesthat follow setsomecharacteristicsof theshowersthataregoingto besimulated.ThePrimaryZenAngle directive givestheshower zenithangle,measuredasindicatedin figure2.1(page12). Thisdirective,andthedirectivePrimaryAzimAngle permittheuserto completelycontroltheinclinationof theshoweraxis.They canbeusedto setthis inclinationto afixedvalue,or to selectvariablesettingsselectedatrandomwith adequateprobabilitydistributions.In thiscasethealternativesyntaxof thedirectivesshouldbeused.For a moredetaileddescriptionseesection3.3.3(page61)and/orappendixB (page114).

The GroundAltitude specificationindicatesthe height above sealevel of the groundsurface(measuredvertically). Thespecificationcanbea lengthor a verticalatmosphericdepthexpressedin


## An example of an AIRES IDL input data set.

Skip &next

The directive "Skip" skips all text until the label &label isfound. Notice that it is not equivalent to a "go to" statementsince it is not possible to skip backwards.

As it can easily be seen, most directive names are self-explaining.&next

Remark JUST AN EXAMPLE

# It is possible to define variables that can be used later within# the input file and/or be passed to output files or special# primary modules.

SetGlobal MyVariable This string is associated with the variable.SetGlobal VRem Another variable.

Remark {VRem} # This expands to: Remark Another variable.

Import HOME # Importing OS environmental variables.

# The input directives define a "task". Tasks are identified by# their task name and (eventually) version. If not defined, the# version is zero.

Task mytask # Use "Task mytask 5" to explicitly set task# version to 5.

# The following three directives are mandatory (have no default# values)

TotalShowers 2PrimaryParticle ProtonPrimaryEnergy 1.5 PeV## The remaining directives allow controlling many parameters of the# simulations. The respective parameters will take a default value# whenever the controlling directive is not present.#

PrimaryZenAngle 15 degThinning 1.e-4 Relative # Relative or absolute

# specifications allowed.

Ground 1000 g/cm2

# You can freely set the number of observing levels to record the# shower longitudinal development. You can define up to 510# observing levels and (optionally) altitude of the highest and# lowest levels.

ObservingLevels 41 100 g/cm2 900 g/cm2

Figure 3.1. SampleAIRESinput.


## Threshold energies. Particles are not followed below these# energies.

GammaCutEnergy 200 KeVElectronCutEnergy 200 KeVMuonCutEnergy 1 MeVMesonCutEnergy 1.5 MeV # Pions, Kaons.NuclCutEnergy 150 MeV # Nucleons and nuclei.

## Some output control statements.#

# Compressed particle data files related directives.

SaveInFile lgtpcles e+ e-SaveNotInFile grdpcles gamma

# Saving the ASCII (portable) version of the IDF file (ADF), after# finishing the simulations.

ADF On

## No tables are printed or exported if no PrintTables ExportTables# directives are explicitly used.#PrintTable 1291 # Longit. devel. of all charged particles.PrintTable 1707 # Energy longitudinal development of muons.PrintTable 2207 Opt d # Setting some options.PrintTable 3001 Opt M # Here too.#ExportTable 2793 Opt M # Exported tables are placed in separate,ExportTable 5501 # plain text files for further processing

# (e. g. plotting).

End # End of input data stream.

Figure 3.1. (continued)


gN cmR (seepage123).On theotherhandthestatement

ObservingLevels 41 100 g/cm2 900 g/cm2

setsthevariableslnm , oqp Ysrm and oqputgv rm of equation(2.19).

The IDL instructionscontinuewith five directives that fix the cut energiesfor differentparticlekinds.Everyparticlewhosekineticenergy fallsbelow thethresholdcorrespondingto its kind will beno morepropagatedby thesimulationprogram,asexplainedin section2.2.3(page23).

Thereare many observablesthat can be definedand studiedto determinethe behavior of airshowers with given initial conditions. Generallyonly a small fraction of theseobservablesareofinterestfor adetermineduser;andof course,thesetof relevantobservablesdovarywith theparticularproblembeingstudied.

Thesesomewhatcontradictoryfactsweretakeninto accountwhendesigningAIRESoutputunits,togetherwith ananalysisof theoutputsystemof existingprograms[1, 30]. As aresult,thesimulationprogramwasprovidedwith two air showerdataoutputunits: Theparticledataunit andthesummaryunit.

The particledataunit generatescompressedparticle data files containingdetailedinformation(in a perparticlebasis)of particlesreachinggroundor passingacrossthedifferentobservinglevels.The other output unit processesdatastoredin a numberof internal tables(or histograms)whichwere calculatedduring the simulationsand which correspondto standard observableslike lateraldistributions,energy distributionsandsoon.

Theoutputsystemwill betreatedin detail in chapter4 (page77). Nevertheless,it is worthwhilementioningherethatthereareseveralIDL directivesthatpermitcontrollingits behavior.

In our exampleof figure3.1 (page51), thedirectivesSaveInFile andSaveNotInFile control thekind of particlesthataresaved in thecorrespondingcompressedfiles, identifiedby their extensions(lgtpclesandgrdpcles).

Thedefault actionfor thefile containingrecordfor theparticlesreachingground(extensiongrd-pcles) is thatall particlekindsmustbesaved. On theotherhand,no particlesaresavedby default inthelongitudinaltrackingparticlefile (extensionlgtpcles). Therefore,thestatements

SaveInFile lgtpcles e+ e-SaveNotInFile grdpcles gamma

meanthat only electronsand positronsare going to be saved in the longitudinal file, and that allparticlesbut gammarays are going to be recordedin the groundparticle file. The particle kindspecificationsmayincludeoneor moreparticleor particlegroupnames(seesection2.2.1).

Theremay be more than oneof thesestatementsfor eachfile, and their meaningdependsontheorderthey areplacedwithin the input datastream.As anexample,let usconsiderthefollowingstatements:

SaveInFile somefile NoneSaveInFile somefile Muons


They ensurethatonly muonrecordswill besavedin file4 somefile: Thefirst statement“clears”,andthesecondenablesmuons.If theorderis changed:

SaveInFile somefile MuonsSaveInFile somefile None

thentheresultis thatsomefilewill beconsidereddisabledbecausethelastNonespecificationpreventsany particlekind from beingsavedin thecorrespondingfile.

The logical switch controlledby the instructionADF On, enablesthe portabledump file, theportableversionof theIDF file.

The summaryunit managesmore than180 output datatablesthat canbe selectively includedwithin theoutputdata. Eachtableis identifiedby a numericalcode,andthedirectivesPrintTablesand ExportTables permit including a table listing within one of the output files, or generatingaseparateplain text file with the correspondingtable, respectively. The completelist of availabletablesis placedin appendixC (page137). No tablesareexportedor “printed” if no Export or Printdirectivesareincludedwithin theinputdata.Noticealsothatthereareseveraloptionsthatmodify theresultingoutput. Suchoptionscontrol thenormalizationof histograms,outputformat,etc. A moredetaileddiscussionon thissubjectis placedin section4.1(page77).

It is stronglyrecommendedto edit aplain text file containingsomeIDL directives,run thesimu-lation programandanalyzetheobtainedoutput. In UNIX environmentsthis canbemadeby meansof thecommand

Aires < myfile.inp

or, alternatively5

AiresQ < myfile.inp

myfile.inp is thenameof thefile containingtheIDL directives.

Input data listing

The output typedat the terminalby any of the simulationprogramswill be similar to the sampledisplayedin figure 3.2. Among other data,AIRES standardoutput includesa listing of the mostimportantinput parameters.All the parametersthat arenot explicitly setwill take a default value.Whendefault valuesare in effect, it is indicatedwith a (D) symbolplacedbeforethe parameter’sdescription.All Thevariablesincludedin this list canbemodifiedby meansof IDL instructions.

Theinput parameterlisting is dividedin sectionsaccordinglywith thedifferentkind of variablesthatcontrolthecomputationalandphysicalenvironmentof thesimulations.Thesesectionsare

4somefileactuallyindicatestheextensionof thecorrespondingfile, like grdpclesor lgtpclesfor example.5TheprogramAir esQusestheQGSJEThadronicmodel.TheQGSJETinitialization routinesdo employ a certaintime

to complete(up to half an hour in somesystems),andthereforethe executiontime of the QGSJETsimulationsmay belonger than the SIBYLL ones. Notice however that oncethe initializationsarefinished,all the relevant datais writteninto a specialfile. In the following invocationsof the programsuchdatawill be readin from the file, thusreducingtheinitialization time.


>>>>>>>> This is AIRES version V.V.V (dd/Mmm/yyyy)>>>> (Compiled by . . . )>>>> USER: xxxxx, HOST: xxxxx, DATE: dd/Mmm/yyyy>>>>

> dd/Mmm/yyyy hh:mm:ss. Reading data from standard input unit> dd/Mmm/yyyy hh:mm:ss. Displaying a summary of the input directives:

>>>>>>>> REMARKS.>>>>

JUST AN EXAMPLE

>>>>>>>> PARAMETERS AND OPTIONS IN EFFECT.>>>>>>>> "(D)" indicates that the corresponding default value is being used.>>>>

Task Name: mytask

RUN CONTROL:Total number of showers: 2

(D) Showers per run: Infinite(D) Runs per process: Infinite(D) CPU time per run: Infinite

FILE NAMES:Log file: mytask.lgf

Binary dump file: mytask.idfASCII dump file: mytask.adf

Compressed data files: mytask.grdpclesmytask.lgtpcles

Table export file(s): mytask.tNNNNOutput summary file: mytask.sry

BASIC PARAMETERS:(D) Site: Site00

(Lat: .00 deg. Long: .00 deg.)(D) Date: dd/Mmm/yyyy

Primary particle: ProtonPrimary energy: 1.5000 PeV

Primary zenith angle: 15.00 deg(D) Primary azimuth angle: .00 deg(D) Zero azimuth direction: Local magnetic north

Thinning energy: 1.0000E-04 Relative(D) Injection altitude: 100.00 km (1.2829219E-03 g/cm2)

Ground altitude: 297.96 m (1000.000 g/cm2)First obs. level altitude: 16.383 km (100.0000 g/cm2)Last obs. level altitude: 1.1733 km (900.0000 g/cm2)

Obs. levels and depth step: 41 20.000 g/cm2

Figure 3.2. SampleAIRESterminaloutput.


(D) Geomagnetic field: Off(D) Table energy limits: 10.000 MeV to 1.1250 PeV(D) Table radial limits: 50.000 m to 2.0000 km(D) Output file radial limits: 100.00 m to 12.000 km (grdpcles)(D) 100.00 m to 12.000 km (lgtpcles)

ADDITIONAL PARAMETERS:(D) Individual shower data: Brief

Cut energy for gammas: 200.00 KeVCut energy for e+ e-: 200.00 KeV

Cut energy for mu+ mu-: 1.0000 MeVCut energy for mesons: 1.5000 MeV

Cut energy for nucleons: 150.00 MeV(D) Bartol inelastic mfp’s: On(D) Gamma rough egy. cut: 2.0000 MeV(D) e+e- rough egy. cut: 2.0000 MeV(D) Hadronic Mean Free Paths: SIBYLL(D) SIBYLL switch: On

MISCELLANEOUS:(D) Seed of random generator: Automatic(D) Atmospheric model: Linsley’s standard atmosphere

>>>>> dd/Mmm/yyyy hh:mm:ss. Beginning new task.> dd/Mmm/yyyy hh:mm:ss. Initializing SIBYLL 1.6 package.

Initialization of the SIBYLL event generator

. . . (eventual output from SIBYLL) . . .

> dd/Mmm/yyyy hh:mm:ss. Initialization complete.> dd/Mmm/yyyy hh:mm:ss. Starting simulation of first shower.> dd/Mmm/yyyy hh:mm:ss. End of run number 1.

CPU time for this run: . . . .> dd/Mmm/yyyy hh:mm:ss. Writing ASCII dump file.> dd/Mmm/yyyy hh:mm:ss. Task completed.

Total number of showers: 2> dd/Mmm/yyyy hh:mm:ss. Writing summary file.> dd/Mmm/yyyy hh:mm:ss. End of processing.

Figure 3.2. (continued)


Run control. Includesall theparameterscontrolling theconditionsof thesimulations,namely, thetotalnumberof showers,thenumberof showersperrun,thenumberof runsperprocessandthe(maximum)CPUtimeperrun. Thedirectivesthatcontrolthesevariablesaredynamic,andmaythereforevary during thesimulations.Thequantitiesdisplayedin the input parameterlistingcorrespondthusto instantaneousvaluesof thementionedparameters.

File names. A listing with thenamesof all thefiles thatwill becreatedduringthesimulations(ex-cluding,of course,internalscratchfiles). A detaileddescriptionof theoutputfiles thatcanbecreatedby thesimulationprograms,togetherwith guidelineson how to managethemcanbefoundin chapter4 (page77); we justgive hereabrief descriptionof them:

Log file (taskname.lgf). Thisfile containsinformationabouttheeventsthattook placeduringthe simulations.It containsalsoa summaryof the input parametersthat werein effect.Mostof thedatathatgoesinto thelog file is alsowritten into thestandardoutputchannel.

Summary file (taskname.sry, also taskname.tex). Outputsummary. This includesgeneralsimulationdataandall thetablesthatwereprintedusingIDL directive PrintTables.

Exported data files (taskname.tnnnn). Plaintext filescontainingoutputtables.

Tasksummary script file (taskname.tss). File containinga summaryof input and outputdata,written in a formatsuitablefor processingwith otherprograms.

Binary dump file (taskname.idf). Thisfile contains(in machine-dependentbinaryformat)alltherelevantsimulationdata.This file is periodicallyupdatedduringthetaskprocessing.In thecaseof aninterruption,it is possibleto restartthesimulationsfrom thelastupdate.The file is alsouseful to obtainrelevant dataafter the simulationis completed,or evenduringit. Thiscanbedonewith thehelpof thesummaryprogramAir esSry.

ASCII dump file (taskname.adf). Portableversionof the IDF file, written at the endof thetask.Like theIDF file, this file canbeprocessedwith thesummaryprogramAir esSry.

Compressedoutput files (taskname.grdpclesand/ortaskname.lgtpcles). Thesefiles containdetailedparticledata.Thegroundparticlefile, for example,consistsof aseriesof recordsof all the particlesthat reachedgroundin specifiedcircumstances.Thanksto the com-presseddataformatting used,it is possibleto save a large numberof particle recordsusinga moderateamountof disk space.Theformat is universal,sothefiles canbewrit-tenby a givenmachineandprocessedin a differentone. TheAIRES systemincludesalibrary of subroutinesto processsuchfiles (seesection4.2).

Basicparameters. A list of geometricalandphysicalshowerparameters.Thesevariablesdefinetheinitial conditionsof the shower simulations(primary particle,axis inclination, etc.), aswellas the settingsthat are in effect for the parametersof the monitoringalgorithms(numberofobservinglevels,rangeof radialdistancesfor outputfiles,etc.).

Additional parameters. Othershower parameters,generallydependingon the modelused. Sincethe interactionsmodelsare replaceable,the type and numberof additionalparametersmay


vary whenchangingsimulationprograms.Thevariablesincludedin this sectionaswell asthedirectives that allow controlling themmay alsobe changedin future versionsof AIRES. Bydefault, only themostrelevant parameters6 arelisted: Quantitiesassociatedwith hiddenIDLdirectives(seeappendixB) arenot included.Nevertheless,AIREScanbeinstructedto producea full listing, by meansof thedirective: InputListing Full .

Miscellaneousparameters. Otherparametersnot includedin theprecedingsections.

3.3 More on IDL directives

3.3.1 Run contr ol

In theexampleof section3.2.5(page50),no specificationsaremadeaboutthedurationof processesandruns.Thisfactshowsupin thevariableslistedin theruncontrolsectionof thelisting of figure3.2(page55),whenthedefault setting,“Infinite” is in effect for thenumberof showersperrun,thenum-berof runsperprocessandtheCPUtime perrun. With suchsettings,theauto-save mechanismforfault tolerantprocessingis disabled:TheIDF file will besavedonly afterfinishingall thesimulationsspecifiedwith theinput directives.

This canbeacceptablefor a shortsimulationin a reliablecomputersystem.For heavy tasksit isrecommendedto split thesimulationsinto processesandruns. It is worthwhilementioningthat theauto-save/restore operationsdo not alter the resultsof the simulations,which arebitwise identicalindependentlyof thenumberof suchoperationsperformed.

The IDL directivesShowersPerRun, MaxCpuTimePerRun andRunsPerProcessprovide ef-fective controlon thecomputationalconditionsof thesimulations.Thefollowing examplesillustratehow themcanbeused.

RunsPerProcess 1MaxCpuTimePerRun 2 hr

Thesetwo instructionsindicatethatanew runshouldbegin every two CPUhours.Sincethenumberof runsperprocessis 1, a new run will alsoimply thebeginning of a new process;in otherwords,the input file will bescannedevery two CPUhours,allowing for eventualchangesin thedynamicalparametersof thesimulations.

RunsPerProcess 4ShowersPerRun 5

HerethemaximumCPUtime is not set,indicatingthat therewill beno time limit for a run to com-plete. Instead,every run will finish afterconcludingthesimulationsof five showers. Theprocesseswill endwhenfour runsarecompleted.

Thethreedirectivescanalsobeusedsimultaneously:

RunsPerProcess 2ShowersPerRun 2MaxCpuTimePerRun 6 hr

6This alsoincludesall thevariablesthatwereexplicitly setby meansof thecorrespondingIDL instructions.


Theseinstructionsindicatethat a run will finish after six processinghoursor after completingtwoshowers,whathappensfirst.

The run control directives–like any otherdynamicdirective– canbe modifiedduring thesimu-lationsif needed.Thechangeswill beeffective aftera new processis started(seesection3.1). Letusassumethata certaintaskis startedwith thecontrolparametersof thepreviousexample.After awhile it is decidedthat themaximumcpu time per run is too high andthat thereis no needto limitthenumberof showersperrun. Theinputfile is thusmodified:(i) TheMaxCpuTimePerRun line isreplacedby

MaxCpuTimePerRun 3 hr

(ii) TheShowersPerRun line is deleted.After finishingthecurrentprocess(with theold settingsthismay demandup to 12 CPU hours),andrestartingthe simulationprogram,the input file is scannedagainandthenew settingswill becomeeffective. Thechangesexperimentedby thesedynamicpa-rameterswill berecordedin thelog file (extension.lgf) in thefollowing way

. . .

> dd/Mmm/yyyy hh:mm:ss. Reading data from standard input unit

> dd/Mmm/yyyy hh:mm:ss. Changing maximum number of showers per run.

From: 2 to: Infinite

> dd/Mmm/yyyy hh:mm:ss. Changing maximum cpu time per run.

From: 6 hr to: 3 hr

. . .

The dynamicdirectives can be changedas many times as needed,including the total numberofshowers(controlledby directive TotalShowers) whichcanbemodifiedeitherduringthesimulationsor aftercompletingthemto appendnew showersto analreadyfinishedtask7.

It is importantto remarkthat themechanismof dividing a taskin severalprocessis possiblebe-causeall therelevantsimulationdatais savedinto theinternaldumpfile, andrecoveredin successiveinvocationsof AIRES.

In someapplications,however, it is necessaryto completelydisablethis mechanism,andforceAIRESto startanew taskevery time anew new processstarts.Thiscanbedonewith thehelpof theForceInit directive, like in thefollowing example:

Task mynameForceInit. . .

Onthefirst invocationof AIRES,thetaskmynamewill beinitializedandexecutedaccordinglywiththeinput directives. In a secondcall, theAIRES initializing procedureswill checkfor theexistenceof the file myname.idf. After finding it, the task versionwill be increasedby one, producingaIDF namedmyname 001.idf, andthenthenew taskwill beexecutednormally. On successive calls,the versionnumberwill be increasedrepeatedly, until finding the first non-existent file with namemyname vvv.idf .

7Noticehowever thatit is notpossibleto appendnew showersto any taskthatwasinitializedwith a previousversionofAIRES.


3.3.2 File directories used by AIRES

Thesimulationprogramsreadand/orwriteseveralfilesthatcontaindifferentkindsof data.By default,all thefilesgeneratedby AIRESarelocatedin theworking directory,definedasthecurrentdirectoryat themomentof invoking AIRES.

Therearecertaincases,however, wherethis settingis not adequate.For that reason,the IDLinstructionsetcontainsdirectivesallowing to controltheplacementof AIRES files.

Let usfirst definethesetof directoriesusedby theAIRESsystemduringthesimulations:

Global. Containingthelog, IDF, ADF andsummaryfiles.

Compressedoutput. Sometimesreferredsimply asOutput directory, containsthecompressedout-put files.

Export. Containingall theexporteddatafiles.

Scratch. Containingmostof the internalfiles that aregeneratedduring the simulations,includingtheparticlestackscratchfiles.

Theoutputandscratchdirectoriesdefault to thecurrentworkingdirectorywhennotspecified.Ontheotherhand,theglobalandexport directorydefault to thecurrentsettingof theoutputdirectory.

TheIDL directive FileDirectory permitscompletecontrolon thelisteddirectories.For example,thesequenceof instructions:

FileDirectory Scratch /mytmpdirFileDirectory Export /myexportdir

setsthe scratch(export) to the strings(mustbe meaningfulto the operatingsystem)/mytmpdir(/myexportdir). Thedirectoryspecificationsmaybeeitherabsoluteor relative. Relative speci-ficationsarealwayswith respectto theworking directory. In theprecedingexamplethe remainingdirectoriesarenot specified,andwill thereforetake their respective default settings.

Thedirective

FileDirectory All /mydir

simultaneouslysetstheglobal,outputandexportdirectories.Thereis anadditionalsetof directoriesthatcanbespecifiedwhile scanningthe input data.The

following instructions,for instance,

InputPath /dir1:/dir2InputPath Append /dir3Input myinputfile.inp

will causeAIRES to searchfor file myinputfile.inp in all thethreedirectoriesspecifiedby meansofthe InputPath directives(noticethetwo alternative syntaxes)and–if not foundthere–in thecurrentworkingdirectory.


3.3.3 Defining the initial conditions

Therearetwo mandatoryspecificationsrelatedto shower parametersthatmustalwaysappearwithintheinputdata,namely, primaryparticlekind andenergy.

Thesetwo specifications,togetherwith otherrelatedonespermita very wide rangeof specifica-tionsfor theshower parameters.Let usinvestigatesomeof thepossiblealternatives.

Mixed composition

Theprimaryparticleneedsnot beunique. AIRES allows for simulatingshowerswith differentpri-maryparticleseach.Thefollowing exampleillustratesthis feature:

PrimaryParticle Proton 0.6PrimaryParticle Iron 0.4

With suchsettings,theprimarywill beproton(iron) with 60%(40%)probability. This meansthatin100simulatedshowers,approximately60 will beprotonshowerswhile theremainingoneswill haveiron primaries.

If w alternative primaryparticles,x�y , z{i|IM}S]S]S]~}�w weredefined,with weights ��y ( ��y��i�L ), thentheprobabilityfor any shower of beinginitiatedby particlex+� , I��w is givenby

� � i � �� q�y�� Y � �� (3.1)

Therefore,theweightsenteredin theIDL directivesneednotbenormalized.

Besidesthis mixed compositionfeature,AIRES allows alsoto definespecialprimary particlesprocessedby externalmodules.For detailsseesection3.5(page70).

Varying energy

Thedirective

PrimaryEnergy ��s��h(seepage129),indicatesthattheprimaryenergieswill bein theinterval � � �� }�� s�~� , selectedwithprobability[22]: x¡ ¢�¤£¦¥ �§i©¨ TgY � T p«ª~¬ Ysr ¥ ��} � �� s� } (3.2)

where

¨�i ®°¯²±´³¢µ¯ ±´¶ · � T p¸ª~¬ Ysr ¥O�kiº¹»»¼ »»½Yª¿¾ � T ª��ÁÀ � T ª��s�QÂ hÃ�iÄLÅ�Æ �� s� NQ� �� £ h°iÄL (3.3)

h cantake any value.If not specifiedit is takenas1.7.


Zenith and azimuth angles

Thezenithangledirective placedin theexampleof figure3.1(page51)correspondsto settingthean-gle to afixedvalue.In thiscasetheazimuthangledefaultsto zero.On theotherhand,theinstruction

PrimaryZenAngle 0 deg 72 deg S

indicatesthatthezenithangledistributesfrom L Ç to ÈM^XÇ with sinedistribution8�ÊÉ ��ÌË~ ÎÍ�£Ï¥:ÍÐi©¨ TgY�Ñ�Ò Æ Í#¥+Ín} Í"��ÓÍk�ÓÍ"��s� } (3.4)

where ¨�i ®ÕÔ ±´³¢µÔ ±´¶ · ÑÖÒ Æ Í#¥:Í�iÄ×ÌØ Ñ Í �� À ×ÌØ Ñ Í ��s� ] (3.5)

An alternative to theS specificationis theSC (or CS) specificationwhich correspondsto a sine-cosinedistribution:� É ��ÚÙÎÛ É ÎÍn£¦¥:ÍÐi�¨ TgY�Ñ�Ò Æ ÍÜ×ÌØ Ñ Í#¥:Í�} Í �� ÝÍk�ÓÍ ��s� } (3.6)

where ¨�i I^ ® Ô ±´³¢µÔ ±´¶ · Ñ�Ò Æ �^ Í�£Ï¥+ÍÐi I_ ��×ÌØ Ñ �^ Í"��O£ À ×ÌØ Ñ �^ Í"��s� £ � ] (3.7)

Forvaryingzenithangles,thedefault for theazimuthangleis touniformlydistributein theinterval� L Ç }ÖfX\ML Ç � . In this casethesinedistribution correspondsto showerswith directionshaving a uniformsolidangledistribution.

Theazimuthanglecanalsobesetasavaryingangle.Thedirective

PrimaryAzimAngle 37.2 deg 39.5 deg

indicatesthattheazimuth Þ will beuniformly distributedin theinterval ��f È:]�^ Ç }ÖfXß+]�e Ç � .Usingsimultaneouslyinstructionsfor boththezenithandazimuthangles,it is possibleto simulate

showerscomingfrom adetermineddirectionin thecelestialsphere.As pointedout in section2.1.1(page11), the à -axis(zeroazimuthaxis)correspondsto thelocal

magneticnorth. If desired,it is possibleto specifygeographicazimuths:

PrimaryAzimAngle 37.2 deg 39.5 deg Geographic

In theprecedingdirective, theGeographickeyword indicatesthattheorigin of theazimuthanglesisthedirectionof the local geographicnorth. It is worthwhilementioningthat this doesnot alter theaxisdefinitionsof section2.1.1;whengeographicazimuthsarein effect, theazimuthwith respecttotheAIREScoordinatesystem,Þ , is evaluatedvia

Þ�iÄá À Þãâ Ë[Û â1ä �æåÌçÌ��Ù (3.8)

8Thesinedistribution is sometimescalledcosinedistribution, relatingit with theaccumulative probability functionofthesinedistribution: è+é ¶ ·sê�ëíì�î´ï°ðgñò°ó é ¶ ·æêæëõôOîMöSô .


whereá is thegeomagneticdeclinationangledefinedin section2.1.5(page19). Noticethatpositivegeographicazimuthsindicateeastwardsdirections. For a completedescriptionof this directive seepage129.

Position of injection, ground and obser ving levels

The directives InjectionAltitude (or its synonym InjectionDepth), GroundAltitude (or its syn-onym GroundDepth) andObservingLevels permit controlling the positionof the injection point,thegroundsurfaceandthedifferentobservinglevels,respectively.

All thealtitudespecificationsreferto verticalaltitudes,notedas ÷Kø in figure2.1(page12),andcanbeexpressedeitheraslengths(above sealevel) or verticalatmosphericdepths.Whenever necessary,AIREStransformslengthsinto verticaldepthsandvice-versausingthecurrentatmosphericmodel.

Notice that the vertical altitudesare equalto the corresponding÷ -coordinatesonly for pointslocatedin the ÷ -axis.To illustratethispoint, let usconsiderthefollowing instructions

InjectionAltitude 100 kmGroundAltitude 1000 mPrimaryZenAngle 60 deg

With suchspecifications,the primary particleswill be injectedat an altitudeof 100 km above sealevel, measuredalongtheverticalpassingby theinjectionpoint. Takinginto accountthattheshoweraxis hasan inclination of 60 degrees,andapplyingequation(2.1), it is possibleto calculatethe ÷ -coordinateof the injectionpoint, alsoreferredascentral injectionaltitude. In this casethe resultis÷~ùúikI~ÈMßX\X^ m.

Thepositionsof theobservinglevelsdefinedin section2.2.3(page26) canbesetusingObserv-ingLevels. This directive hastwo differentformats:

(i) ObservingLevels l�m , with lnm anintegernot lessthan4.

In this casethepositionsof theobservinglevels aresettaking into accountthe injectionandgroundverticaldepths.Let o�y ( o�û ) betheinjection(ground)depth,thenthespacingbetweenobservablesandthepositionsof thefirst andlastobservinglevelsaresetviaü o&mÝi o�û À o�yl m�ý Ioqp Ysrm iþo�y ý ü o&mo put v rm iþo�û À ü o&m

(3.9)

(ii) ObservingLevels lnm{o&ÿÁo�� , with l�m anintegernot lessthan4 and o&ÿ and o�� valid verticaldepthor altitudespecifications( o&ÿa�i o�� ).In this secondcasethepositionsof thefirst andlastobservinglevelsaresetaccordinglywitho&ÿ and o�� , with no dependenceon thepositionsof theinjectionandgroundlevels:o p Ysrm i�� Ò Æ ¢o&ÿ }�o��7£�} o put v rm i��g ¢o&ÿO}�o��7£�] (3.10)

Thespacingbetweenconsecutive levelsis evaluatedusingequation2.19.


Sitename Latitude Longitude Altitude (m.a.s.l)

Site00 0.00Ç 0.00Ç 0SouthPole 90.00Ç S 0.00Ç 3127ElNihuil 35.20Ç S 69.20Ç W 1400Millard 39.10Ç N 112.60Ç W 1400AGASA 35.78Ç N 138.50Ç E 900CASKADE 49.09Ç N 8.88Ç E 112Dugway 40.00Ç N 113.00Ç W 1550ElBarreal 31.50Ç N 107.00Ç W 1200FlysEye 41.00Ç N 112.00Ç W 850HaverahPark 53.97Ç N 1.64Ç W 220Puebla 19.50Ç N 98.00Ç W 2200SydneyArray 30.50Ç S 149.60Ç W 250Yakutsk 61.70Ç N 129.40Ç E 850

Table3.2. Predefinedsitesof theAIRESsitelibrary. Sitenamesarecasesensitive. ThedataforHaverah Park, Sydney ArrayandYakutsksitescomefromreference[28].

3.3.4 Geomagnetic field

The componentsof the Earth’s magneticfield usedby the simulationprogramscan either be setmanuallyor calculatedwith thehelpof theIGRF model[8] (seesection2.1.5).With thehelpof thismodelit is possibleto obtainanaccurateestimationof thegeomagneticfield in a givengeographiclocationandfor adetermineddate.

To activate this mechanismfor “automatic” evaluationof the magneticfield, it is necessarytospecifybotha geographicplaceandadate.

Thedirective Site tells AIRESthenameof thesiteselectedfor thesimulations.For example,

Site SouthPole

indicatesthat the selectedplaceis “SouthPole”. This nameis oneof the predefinedlocationsthatform the AIRESsite library. Besides“SouthPole”,this library initially containsseveral othersitesrelatedwith air shower experiments.All thepredefinedsitesarelistedin table3.2.

To specifya site that is not includedamongthe predefinedones,it is first necessaryto appendit to thesite library by meansof theAddSite directive. Let usconsider, for instance,the followingdirective:

AddSite cld -31.5 deg -64.2 deg 387 m

A new site“cld” is defined.Thecommandparametersrepresent,respectively, thelatitude,longitudeandaltitudeabove sealevel thatcorrespondto thedefinedsite.Thenamestringcannotcontainmorethan16 characters;namesarecasesensitive andmustbedifferentto all thepreviously definedones.


TheDate directive definesthedateof anevent. Therearetwo alternative syntaxes,asdisplayedin thefollowing examples:

Date 1998.2Date 1998 3 1

In thefirst statementthedateis givenasafloatingpointnumbertakingtheyearasthetimeunit,whilein thesecondtheformat“year monthday” is used.

Thereareno specialrestrictionson the datespecification.However, the IGRF databaseimple-mentedin the currentAIRES versioncontainsdatafor the years1955to 1995. For datesoutsidethatinterval it is necessaryto extrapolatethecorrespondingdatain orderto evaluatethegeomagneticfield. This mayleadto inaccurateestimationsfor datesvery far from thevalidity rangeof themodel(morethanten yearsaway). Nevertheless,extrapolationsnearthe given boundariesareacceptable,andareof coursenecessaryfor calculationsbeyondtheyear1995.9

In caseof missingdatespecification,it is setaccordinglywith thesystemtime at themomentofstartingthesimulations.

Onceasiteandadateareset,theEarth’s magneticfield will becalculatedby meansof theIGRFmodel,unlessit is explicitly setby meansof theGeomagneticFielddirective. Let usanalyzesomeexamples(seealsopage123):

GeomagneticField Off

With this instructiontheeffect of themagneticfield on themotionof thechargedparticleswill notbetakeninto account.However, thefield will still beevaluatedin orderto determinethedeclinationangle,which is usedto transformgeographicalazimuthsinto magneticones(seepage62).

GeomagneticField 32 uT -60 deg 2 deg

The precedingdirective instructsAIRES to fully override the IGRF estimationwith the valuesin-dicatedin the parameters,which respectively correspondto F, I andD (seesection2.1.5). Partialoverridingis alsosupported,like in thefollowing instruction

GeomagneticField 32 uT

Thefield strength,F, will besetto thevalueindicatedin thefirst parameter, while I andD will remainasgivenby theIGRF model.àÏ÷ -planeGaussianfluctuations,eitherabsoluteor relative,arealsosupported:

GeomagneticField 32 uT Fluctuation 500 nTGeomagneticField On Fluctuation 10 %

Noticethatfluctuationscanbe introducedwith or without overridingtheIGRF field components.Itis alsopossibleto specify0.1Relative insteadof 10 % .

9Thenext generationof IGRF datawill bereleasedaftertheyear2000.


Whenmagneticfluctuationsarein effect, thenthe magneticfield usedfor eachshower will bedifferent. Let

�bethe“central” valuecomingfrom theIGRF modeland/orenteredmanually. Letü��

bethespecifiedfluctuations.Noticethatin thecaseof relative fluctuations,ü��

is setusingthefield strength

� :ü�� i � ü�� ä Ë � .

Thenfor eachnew shower, two independent,Gaussian-distributed randomnumbers,ü��

andü��, having meanzeroandstandarddeviation

ü�� N � ^ , aregenerated;andthemagneticfield com-ponentsaresetvia �� i � � ý ü�� }�� i � � ý ü�� ] (3.11)

Notice,however, that thedeclinationangleusedfor azimuthtransformationswill alwayscomefromthecentralvalue,thatis, is notaffectedby thefluctuationsintroduced.

3.3.5 Statistical sampling contr ol

Thethinningalgorithmdescribedin section2.3 (page27) makesuseof severalexternalparametersthat canbe setby meansof IDL directives. The thinningenergy �� is themost importantparam-eterof the thinningalgorithm. As illustratedin figure3.1 (page51), thedirective ThinningEnergypermitssetting�� , eitherabsolutelyor relative to theprimaryenergy.

Thedirective ThinningWF actor allows controllingthemaximumweightparameter�� !#"%$ de-finedin section2.3(page27). Thespecification

ThinningWFactor 2.5

setstheweightfactor, �'& , of equation(2.23)to 2.5,to beusedwith electromagneticparticles.

Recommendedvaluesfor �(& arein therange0.1to 50; thedefaultvalueis 12. Setting�(&�)+*-,.,is practicallyequivalentto �(&0/21 (seesection2.3.3).10

Theweight factorthat is usedwith nonelectromagneticparticles,� �435 & , canalsobesetby theuser:Thedirective EMtoHadr onWFRatio permitssettingtheratio 6 ��3 definedin equation(2.24).The default value 6 �7398 :.:

is normally adequate,but someapplicationsmay requireperformingsimulationswith adifferentrelationbetweenelectromagneticandnonelectromagneticweightfactors,andin suchcasesthementioneddirective is usefulto changetheratio asneeded.

3.3.6 Output table parameter s

Theoutputtableslistedin appendixC (page137)areautomaticallycalculatedduringthesimulations,andthedirectivesto retrieve thesedatawill beexplainedin chapter4 (page77). Many of thesetablescanbecustomizedby meansof IDL instructions.

10IMPORTANT: Thestatisticalweightfactorof theAIRESextendedthinningalgorithmis notequivalentto theparam-eterwith thesamenamedefinedfor AIRES1.4.2or earlier. Therefore,therecommendedvaluesplacedin theAIRES1.4.2manual[12] donotapplyfor thecurrentversion.


Thenumberof observinglevelsdefinedfor thelongitudinaltables(tablenumbers1000to 1999)canbe controlledusing the IDL directive ObservingLevels, as alreadyexplainedin section3.2.5(page50).

Thelateraldistribution tables(tablenumbers2000to 2499),theenergy distribution tables(tablenumbers2500to 2999),andthemeanarrival time distribution tables(tablenumbers3000to 3499)aredefined,by default,ashistogramswith 40logarithmicbins(eitherradialor energy binsdependingon thedistribution type),plustwo additional“underflow” and“overflow” bins.

TheIDL directivesRLimsTablesandELimsTablesallow to control theradialandenergy bins,respectively, asillustratedin thefollowing examples:

RLimsTables 20 m 2 kmELimsTables 2 MeV 1 TeV

Thefirst directivesetstherangefor thestandardlateraldistributions.Thelowestendof bin 1 (highestendof bin 40) is setto 20 m (2 km). The “underflow” bin will thuscorrespondto all entrieswithdistanceslessthan20 m, while the“overflow” oneto all entriesbeyond2 km.

In a completelysimilar way, theseconddirective setsthelower andupperboundsfor the40 binenergy distributions,andtherespective “underflow” and“overflow” bins.

With thecurrentversionof AIRES it is possibleto save thetablesin a shower pershower basis,besidesthetraditionalaveragetablesthathave beenalwaysavailable. Sincethis maygeneratelargeIDF or ADF files in certaincases,the mechanismof individual shower tablesaving is disabledbydefault. Thedirective

PerShowerData Full

mustbeusedto ensurethattheindividual shower tablesarebeingsaved.

3.3.7 Random number generator

TheAIRES randomnumbergeneratormustbeinitialized beforestartingany setof simulations.Thedefault action is to usea internally generatedseed,generatedwith an elementaryrandomnumbergeneratorthat usesthe currentclock andCPU usageregisters. Therefore,different invocationsofAIRESwith thesameinputdirectives,will generallyoriginatedifferentoutputdatabecauseof differ-entinitializationsof therandomnumbergenerator.

Thedefault behavior canbechangedif needed.ThedirectiveRandomSeedallows theuserto settherandomseedto agivennumber, or to gettheseedfrom analreadyinitialized task.Thesefeaturesareillustratedin thefollowing examples:

1. Thedirective

RandomSeed 0.1298004637

setstherandomseedto a fixedconstant.Thenumbermustbegreaterthanzeroandlessthanone.


2. Thedirective

RandomSeed GetFrom otheridfile

extractstheseedusedin the taskthatcreatedthe IDF file otheridfile, andusesit to initializethegenerator.

3.4 Input parameter s for the interaction models

The expressioninteraction modelsidentifiesa seriesof subroutinesand functionsthat containtheactualimplementationsof thealgorithmsthat control thepropagationof particles.Suchalgorithmsemulatethephysicalrulesassociatedwith thedifferentinteractionsthattake placein anair shower.

As it is well-known, therearestill many openproblemsin this areaandthereforetheinteractionmodelscannotbe considereda crystallizedpart of the simulationprograms. Furthermore,in thedesignof theinteractionmodelsandexternalpackagesunitsshown in figure1.1(page7), everyeffortwasmadeto make themeasilyreplaceable,in orderto be ableto incorporateimproved codeto bedevelopedin thefuture.

TheIDL directivesthataregoingto bementionedin thissectionallow theuserto controldifferentmodelparameters.Suchdirectivesaredefinedfrom within theinteractionmodelsection,andfor thereasonsexplainedin theprecedingparagraph,they areof achangingnature:For AIRESversionslaterthanthecurrentversion2.6.0themodelrelateddirectivesmayno longerbesupported,be replacedby alternative onesor their syntaxbetotally or partiallychanged.

3.4.1 External packages

Both SIBYLL [6] andQGSJET[7] hadroniccollisions packagesare implementedin AIRES. Fortechnicalreasonsthey arecompile-timeimplemented,andareavailableby meansof two differentexecutableprograms:Air esandAir esQcontaininglinks to SIBYLL andQGSJET, respectively.

The currentversionof AIRES (2.6.0) includeslinks to SIBYLL 2.1 andQGSJET01.The oldversionsSIBYLL 1.6 andQGSJET99arealsodistributed,andcanbeusedinvoking theexecutableprogramsAir esS16andAir esQ99, respectively.

All the particle-nucleusandnucleus-nucleusinteractionswith projectilekinetic energy above acertainthresholdareprocessedusingtheexternalpackage,while thelow energy onesarecalculatedby meansof theextendedHillas splittingalgorithm[4, 22], or abuilt-in nuclearfragmentationmodel,in thecasesof hadron-nucleusor nucleus-nucleuscollisions.

TheIDL directiveExtCollModel is anOn-Off switchthatallows controllingtheuseof theexter-nalpackage(SIBYLL or QGSJET,dependingontheexecutableprogrambeingused).Theminimumenergy requiredfor theexternalpackageto be invoked canbealteredusingdirectivesMinExtCol-lEnergy and/orMinExtNucCollEner gy, asin thefollowing example:

MinExtCollEnergy 300 GeVMinExtNucCollEnergy 500 GeV


AIRES supportsalsothedirective ForceModelNamethat is usefulto ensurethata given inputdatasetwill beprocessedonly with a determinedsimulationprogram.For instance,if an input datasetcontainingtheinstruction

ForceModelName QGSJET

is processedwith other simulationprogramdifferent from Air esQ, the processwill immediatelybe abortedwith an error message.When the directive is not usedno checkis performedand thesimulationscanbestartedwith any program.

Thecrosssectionsusedto determinethecollision meanfreepathscanalsobecontrolled.In thecurrentversionthereareseveral setsof hadroniccrosssectionsavailable,namely, Standard,Bartol[1], QGSJETandSIBYLL crosssections.TheoptionsQGSJET99andSIBYLL16 arealsoavailable.

Thedefault meanfreepathsaretheonescorrespondingto theexternalhadronicpackagelinkedto the simulationprogram,that is, the SIBYLL (QGSJET)set for programAir es (Air esQ). Thefollowing exampleillustrateshow to alterthedefault settings:

MFPHadronic BartolMFPThreshold 120 GeV

Theseinstructionsimply that the “Bartol” meanfreepathswill be usedfor collisionswith energiesover120GeV, while thestandardmeanfreepathswill beusedfor theoneswith lowerenergies.

Theprevious directivesalsoindicatethat thenucleus-nucleusmeanfreepathswill beevaluatedusingspecialalgorithmsincludedwithin theexternalhadronicpackagesif theprojectile’s energy pernucleonfallsabove thespecifiedthreshold;otherwisethemeanfreepathwill beevaluatedvia abuilt-in procedurethatcalculatesit by scalingadequatelytheproton-nucleusmeanfreepathcorrespondingto the modelbeingused. The directive ExtNucNucMFP allows to disablethe call to the externalroutine,andusethebuilt-in algorithmfor all projectileenergies.

Thehadron-nucleus/nucleus-nucleus and/orthephoton-nucleuscollisionscanbedisabledif de-sired:

NuclCollisions OffPhotoNuclear Off

Thesesettingsareintendedto beusedonly for specialpurposes:Theresultsobtainedin suchcondi-tionsmayberatherunphysical.

3.4.2 Other contr ol parameter s

ThereareseveralIDL instructionsthatallow controllingdifferentparametersand/orprocessesof thesimulationalgorithms.TheseIDL directivesneednotbeusedfor normaloperation.Furthermore,theusershouldtake into accountthatimpropersettingsfor someof theparametersassociatedwith theseinstructionsmayleadto unphysicalresults.

PropagatePrimary. Logical switchto controltheinitial propagationof theprimary.


SetTimeAtInjection. Logical switch to controlwhetheror not theshower time is setto zeroat theinjection point. The shower clock canbe set to zeroat the injection point (default) or at themomentof thefirst primaryinteraction.

GammaRoughCut,ElectronRoughCut. Thresholdenergiesfor “normal” propagationof gammasandelectrons,respectively. Particleswith kineticenergiesbelow thosethresholdsare“roughly”propagated,thatis, many processesarecalculatedonly approximately, or areignoredat all.

ForceLowEDecays,ForceLowEAnnihilation. Thesedirectivescontrol thekind of actionto beta-ken when low energy particlesthat candecayor undergo annihilationreachthe low energythreshold.

LPMEffect. IDL switchto enable/disabletheLPM [19, 24] effect. Thedefault is LPMEffect On.

DielectricSuppression. IDL switchto enable/disablethedielectricsuppression[19, 25] effect. Thedefault is DielectricSuppressionOn.

MuonBr emsstrahlung. IDL switchto enable/disablethemuonbremsstrahlungandmuonicpairpro-ductionprocesses.Thedefault is MuonBr emsstrahlungOn

AirZeff, AirA vgZ/A, AirRadLength. IDL directivesassociatedwith internalparameters.For ade-tailedexplanationseeappendixB (page114).

Sincemostof theseIDL instructionsarehiddendirectives(seepage58) therespective settingsineffect will not beincludedin theinput datalist, unlessexplicitly indicatedby meansof directive In-putListing (seepage124).Additionally, warningsmessageswill beissuedwhenusingany directivewhichmayleadto simulationswith unphysicalresults.

3.5 Special primar y par tic les

In many casesof interest,it is necessaryto simulateshowers that cannotbe describedadequatelywith theusualschemeof a singleprimaryparticleinteractingwith a nucleusin theatmosphereandgeneratinga setof secondariesto be propagated.Instead,onehasthat a particularsetof interac-tionsthatonly affect theprimaryparticle,originatesa seriesof “normal” secondaryparticlesthathitthe atmosphereandoriginatethe correspondingcascades.In general,suchspecialinteractionsarenot modeledadequatelyby AIRES propagatingengine,but it is possibleto overcomethis difficultyallowing the simulationprogramto starta shower with multiple “primary” particleswhich are thesecondariescomingout from the“special” interactions.

Thefollowing areexampleswherethementionedschemeapplies:; An exotic cosmicparticle(a cosmicneutrino,for instance)interactsandproducesa seriesofparticlesthatcanbenormallypropagatedby AIRES.

CHAPTER 3. STEERING THE SIMULATIONS 71; An electromagneticparticle interactswith the Earth’s magneticfield before reachingthe at-mosphere,andproducinga pre-showerwhoseproductsfinally reachtheatmosphereandstartinteractingwith it.; A cosmicparticledisintegrates(beforereachingtheEarth)in two or morefragmentsthatarrivesimultaneouslyin slightly distantpoints.; Etc.

AIRES 2.6.0allows theuserto simulateshowersinitiated in suchconditions.An external,userprovided,programwill beresponsiblefor generatingtheparticlesto be injectedat thebeginningoftheshower. Thisprocessis completelydynamic,andthesetsof generatedprimaryparticlesmayvaryfrom shower to shower.

To implementsuchaninterfaceis very simple.Theuserneedsto: (i) Definethespecialparticlewithin theIDL instructions.(ii) Setup theexternalprogramthatwill be invoked (via a systemcall)at themomentof startinganew showers.

3.5.1 Defining special par tic les

TheAIRES IDL directivesallow to specifyparticlesby names(“proton”, “gamma”,etc.).Thesetofknown particlenamescanbeexpandedto includethosespecial“particles” which needto betreatedseparately.

Considerthefollowing examples:

AddSpecialParticle myparticX XpartsimAddSpecialParticle myparticY Xpartsim type Y

TheIDL directive AddSpecialParticle takesat leasttwo arguments:(i) A specialparticle namethatuniquelyidentifiestheaddedspecialparticle,and(ii) Thenameof theexecutablemodulethatwill beinvokedwhenstartingtheshowersinitiatedby therespective particles.

In theprecedingexample,two specialparticles,namely, myparticX andmyparticY aredefinedandassociatedto thesameexternalmodule,Xpartsim . In thecaseof thedefinitionof myparticY ,someargumentsarespecified(“ type Y”). Suchargumentsarepassed(portably)to themodule.

Oncethespecialparticle(s)aredefined11, their namescanbeusedasargumentof thePrimary-Particle directive:

AddSpecialParticle myparticX Xpartsim. . .PrimaryEnergy 20 EeVPrimaryParticle myparticX

11Up to tendifferentspecialparticlescanbedefinedfor a giventask.


Specialparticlescanalsobe usedin the caseof mixed composition(seepage61), like in thefollowing example:

AddSpecialParticle SSP1 module 1AddSpecialParticle SSP2 module 2. . .PrimaryParticle SSP1 0.2PrimaryParticle SSP2 0.3PrimaryParticle Proton 0.5

In this casethe primary will be SSP1, SSP2, or proton with probabilities20%, 30%, and 50%,respectively.

3.5.2 The external executab le modules

Every time a specialprimary shower is started,the simulationprogramwill invoke the executablemoduleassociatedwith thecorrespondingprimary, definedusingtheAddSpecialParticle directive.SuchanexecutableprogramcanbeaFORTRAN, C or C++program(or ashellscriptrunningit), andmustbecapableof providing thecalling modulewith the list of primaryparticlesthatwill beaddedto theparticlestacksbeforestartingthesimulationof thatshower.

Thesimulationprogramandtheexternalmodulecommunicatevia internalfiles in a way that istransparentfor theuserandcompletelyportable.

TheAIRESobjectlibrary includesaseriesof user-friendly routines(callablefrom FORTRAN, Cor C++) thateasethetaskof writing suchexternalmodules.

Figure3.3displaysa brief FORTRAN programwith thebasicstructureneededin every modulecapableof building a list of primaryparticlesto startthesimulationof ashower.

Theprogramstartswith a call to routinespeistart andendswith a call to speiend. It is essentialto maintainthis structurein any externalmodule:All thecallsto any AIRES library routinemustbeplacedwithin thementionedcalls.

Oncetheinterfaceis started,thesystemis readyto acceptprimaryparticlesthatwill beaddedtotheprimaryparticlelist. Thebasicroutineto addprimariesto thelist is spaddp0. For eachinvocationof this routine,thecorrespondingparticleis addedto the internallist of particles.Thereis no limitin the numberof primary particlesthat canbe includedin the mentionedlist, but the sumof theirenergiesmustnot be larger thantheprimaryenergy specifiedin the input instructionsandstoredinthevariableprimary energy appearingin figure3.3.

Argumentsnumber3 to 6 of routinespaddp0definethedirectionof motionof thecorrespondingparticle. Argumentnumber3 is an integer switch selectingthe coordinatesystemto useand theremainingquantitiesgive the componentsof a vector, not necessarilynormalized,pointing in thedirectionof motionof theparticle.Therearetwo optionsfor argumentnumber3 (variablecsysin thedescriptionof page201):

0 To selecttheAIREScoordinatesystemdefinedin section2.1.1(page11).


cc An example of an external module to process "special" primaryc particles.c

program specialprim0c

implicit nonecc Declaration of variables retrieved when starting the interfacec with the calling program.c

integer shower_numberdouble precision primary_energydouble precision default_injection_position(3)double precision injection_depth, ground_depthdouble precision ground_altitude, d_ground_injdouble precision shower_axis(3)

cinteger rcdouble precision urandomt

cc Some particle codes (AIRES coding system).c

integer pipluscode, piminuscodeparameter (pipluscode = 11, piminuscode = -11)

cc FIRST EXECUTABLE STATEMENT.cc Starting the AIRES-external module interface.c

call speistart(shower_number, primary_energy,+ default_injection_position, injection_depth,+ ground_altitude, ground_depth,+ d_ground_inj, shower_axis)

cc Injecting two particles at the initial injection point, and inc the direction of the shower axis.c

e1 = primary_energy * urandomt(0.05d0)e2 = primary_energy - e1

ccall spaddp0(pipluscode, e1, 1, 0.d0, 0.d0, 1.d0, 1.d0, rc)call spaddp0(piminuscode, e2, 1, 0.d0, 0.d0, 1.d0, 1.d0, rc)

cc Completing the main program-external module interchange.c The integer argument of routine "speiend" is an integer returnc code passed to the calling program. 0 means normal return.c

call speiend(0)c

end

Figure 3.3.A samplemodulefor processingspecialprimaryparticles.Thepurposeof thisexampleis to illustratethebasicstructure of a programto processthespecialprimaries;theprogrammedalgorithmis not intendedto haveanyvalidity fromthephysicalpoint of view.


<=

>>�?@

<BA= A> A@ A

shower axis

Figure 3.4. Theshoweraxis-injectionpointcoordinatesystem,CED�FGDIHJD (magenta),contrastedwith theAIREScoordinatesystem,CBFKH (green).Theorigin of theAIREScoordinatesystem,L , is locatedatsealevel,while L�D is locatedat theoriginal showerinjectionpoint. H-M is thegroundaltitude. TheHJD -axisis parallel to theshoweraxis,the CED -axisis alwayshorizontal,andthe FGD4H.D -planecontainsthe H -axis.

1 To selectthe showeraxis-injectionpoint system. This is a specialcoordinatesystemwhoseH -axisis parallelto theshoweraxisandits origin is placedat theoriginal injectionpoint (whichremainsuniquelydeterminedby theshowerzenithandazimuthanglesandby theinjectionandgroundaltitudes).In this coordinatesystem,illustratedin figure3.4, thecoordinatesNO,QPR,QPSHJDUTandthevector NO,QPR,QPV*�T indicate,respectively, thepositionanddirectionof motionof a particlethatmovesalongtheshower axisandtowardstheground.

Theprocessis completedwith thecall to speiend. This ensuresthatall therelevantvariablesaretransmittedbackto the main simulationprogram,which will recover the control after the externalmoduleends.Bothspeistartandspeiendmustbecalledonly oncewithin theentireexternalmodule.

Noticealsothatoneof theAIRES randomnumberroutines,namely, urandomt (seepage213),is usedto evaluatethe energy if the W mesonsbeingincludedin the list of primary particles. Therandomnumbergeneratoris not initialized. Instead,its currentstatusis passedby themainsimula-tion programto theexternalmodule,andread-inwithin speistart. As a consequence,thegeneratedrandomnumberswill be different in differentinvocationsof the externalmodule. Routinespeiendwritesbackthefinal statusof therandomnumbergenerator, andit is recoveredby themainsimula-tion program,sothenumbersusedin oneandotherprogramarealwaysindependent.If theAIRES


randomnumbergeneratoris not usedwithin theexternalmodule,thenthereareno alterationin theseriesof randomnumbersusedby themainsimulationprogram.

An actualexternalmoduletoprocessspecialprimarieswill surelybemuchmorecomplex thantheoneof theprecedingexample.Theusercanprovide specialroutineswith theproceduresneededforthatpurpose,anduseroutinesfrom theAIRESobjectlibrary aswell. Many of themodulesdescribedin appendixD (page144)canbeusedwithin specialprimaryprograms,in particulartheonesdirectlyrelatedwith thespecialparticleinterfacesystem,which provide a setof toolscovering theneedsofthemostcommonsituations,namely:

Retrieval of environmental information. Routinespeistart startsthe AIRES-externalmodulein-terfaceandretrievessomebasicvariables,namely, shower number, primary energy, originalinjectionposition(threecoordinates),verticalatmosphericdepthof theoriginal injectionpoint,groundlevel altitudeandvertical atmosphericdepth,distancebetweenthe original injectionpointandthegroundlevel (measuredalongtheshoweraxis),andunitaryvectorin thedirectionof theshoweraxis.Besidesthesevariables,it is possible(optionally)to retrieveadditionalonescallingotherroutinesincludedin theAIRESobjectlibrary:; speigetpars(page205) returnstheparameterstring thatcanbe(optionally)specifiedin

theIDL instructionthatdefinesthecorrespondingspecialparticle(seedirective AddSpe-cialParticle, page115). The simulationprogrampassesthe argumentstring directly,without makingany specialprocessingon it.; speigetmodname(page204)returnsthenameof theexecutablemodulespecifiedin thedefinitionof thecorrespondingspecialparticle.; sprimname (page211)returnsthenameof thespecialparticlecorrespondingto thecur-rentinvocationof theexternalmodule.; speitask(page209)returnsthecurrenttaskname.; spnshowers (page210) returnsthreeintegersthat correspond,respectively, to the totalnumberof showersassignedto the task,andthe numbersof the first and last showers.Thesequantitiesarerelatedto thespecificationsenteredwith thedirectivesTotalShowersandFirstShowerNumber. Thevariableshower number setwhencallingspeistart (seefigure3.3),will alwaysbeequalor larger(smaller)thanthefirst (last)shower number.

Adding primary particles to the primary particle list. Routinespaddp0 appendsto the particlelist the particle definedwith the argumentsusedin the correspondingcall, as illustratedintheexampleof figure3.3. Additionally, therearetwo otherrelatedlibrary routinesavailable,namely, spaddpn(page202)to appendwith asinglecall asetof variousprimaryparticles,andspaddnull (page200) to includenull (unphysical)particles.A null particleis not includedinthesimulations,but its energy is addedto theglobalnull particleenergy counter. Nuclei canbenormallyappendedto theparticlelist. Nuclearcodescanbeconvenientlyevaluatedusingroutinenuclcode(page189).


Changing the injection coordinatesand time. After theinitial call to speistart, theinjectionpointis setto theoriginal injectionpoint definedby theglobalparametersenteredwithin the inputdata(zenithandazimuthangles,etc.). Thecoordinateswith respectto theAIRES coordinatesystemof theoriginalinjectionpointarereturnedby speistart(thiscorresponds,in theexampleof figure3.3, to arraydefault injection position). The injectioncoordinatesandtime canbechangedatany momentusingroutinespinjpoint (page207).

Setting the point of first interaction. Whenusingnormalprimary particles,AIRES evaluatesau-tomatically the atmosphericdepthwherethe first major interactiontakes place. This is notpossiblein thecaseof a specialparticlewhena seriesof primariesareinjectedbeforestartingthesimulations;andthedefault actionwill beto setthefirst interactionat theoriginal injectionpoint, regardlesswhetherthat pointscorrespondsor not to an actualpoint of interaction. Asan alternative to the default action,it is possibleto setmanuallythe coordinatesof the pointof first interactionusingroutinesp1stint (page199). Of course,this affectsonly thestatisticalanalysisof thefirst interactiondepth,andhasno effecton thepropagationof theparticles.

Versionof external module. The usercan assigna versionnumberto the external module. Thisversionnumbermustbepassedto themainprogramby meansof routinespeimv (page206).The versionnumberis storedwith all the informationassociatedwith the currentshower, inparticularin thecompressedoutputfiles. It is stronglyrecommendedto assignversionnumbersto externalmodulesthatwill beusedin productionsimulations.

Werecallherethatall thecallsto everyoneof theroutineslistedin thepreviousparagraphsmustbeplacedafter thecall to speistartandbefore thecall to speiend.

TheIDL directive SpecialParticLog allows to print informationabouttheprimaryparticlesthatareinjectedaftereachinvocationof theexternalmodule.Noticethat thedefault is to print no infor-mationin thelog (extensionlgf) file.

Chapter 4

Managing AIRES output data

4.1 Using the summar y program AiresSr y

Every time a taskis completed,thesimulationprogramsinvoke someoutputproceduresthatcreatea summaryfile displayinga seriesof resultsrelatedwith the alreadyfinishedsimulations;a tasksummaryscript file canalsobecreated.As it will bediscussedin this section,thereareseveral IDLdirectivesthatallow controllingsuchAIRESoutputdata.

Thesummaryprogram,Air esSry, which is partof theAIRES systemallows theuserto processthesimulationdatacontainedwithin the internal dumpfile (IDF) or, equivalently, theportabledumpfile (ADF), andretrieve any of theavailableobservables,similarly asthemainsimulationprogramsdo. It is worthwhilementioningthatAir esSrycanbeusedbefore aswell asafter thesimulationsarefinished. In thefirst caseit is possibleto monitor thedevelopmentof thesimulationtaskwhile theformeralternative is mostconvenientfor analysistasks.Backwardscompatibility is alwaysensured:Old IDF’sor ADF’sgeneratedwith any previousversionof AIRES canbeprocessednormallyusingAir esSry.1

Many observablesareof “tabular” nature,that is, anarrayof datawhoseelementscorrespondtoa setof valuesof a determinedvariable. For example,the longitudinaldevelopmentof the numberof gammaraysis representedby anarraywhoseelementsgive thenumberof gammaraysthathavecrossedthedifferentobservinglevels,asa functionof theobservinglevel altitude.

Mostof thetabularobservablescommonlydefinedareautomaticallycalculatedby thesimulationprograms.The correspondingdataarraysarestoredin the IDF file andcanbe retrieved in severalways (seebelow). The completelist of currently available output datatables(more than 180) isplacedin appendixC (page137).

1Notice,however, thata setof simulationscreatedusinga determinedversionof AIRES mustbeendedusingthesameversion.

77

78 CHAPTER 4. MANAGING AIRES OUTPUT DATA

4.1.1 The summar y file

The summaryfile (extension.sry) can be divided into two parts: (i) The generalsection,whichincludesdataon the evolution of the simulationsas well as somebasicshower observables. (ii)Tablessection,containingdatatablesaccordinglyto user’s specifications.

The summaryfile is generallywritten as a plain text file (this is the default). However, theIDL instructionLaTeX permitsgeneratingsummariesthat canbe processedusingthe LATEX type-settingsystem.If theLATEX switchis enabled,thentheAIRESsystemwill generatetwo files,namelytaskname.sry andtaskname.tex. Thelastof thesetwo files canbenormallyprocessedby astandardLATEX system.

On the other hand,it is also possibleto instruct any of the AIRES programsnot to write thesummaryfile. To do this, just includethedirective Summary Off into theinput datastream.

General section

The generalsectionof the summaryfile begins with computerrelatedinformation (task and useridentification,CPU time usage,etc.). It alsoincludesinformationaboutthe input parametersused,andreportson the numberof particleentriesprocessedat eachstack. A completereporton stackusagecanbeobtainedusingtheIDL directive

StackInformation On

Thengeneralinformationaboutthenumberandenergy of particlesreachinggroundis displayed.For all the outputobservables,its mean2, standarddeviation, root meansquareerror of the mean,minimumandmaximum,arereported.

TheIDL directiveOutputListing Full will generateanadditionalsectioncontaininginformation(generallyof computationalnature)onseveraloutputquantitiesdefinedfor differentalgorithms.

Thegeneralsectionconcludeswith reportsontheverticaldepthof thefirst interaction,andonthelocationof theshowermaximum.

Thedatacollectedfor the longitudinaldevelopmentof all chargedparticles,that is, thenumberof chargedparticlesXZYVNO[\T thatcrossedtheobservinglevel [ , for all [ 8 *JP-]-]-]^PRXZ_ , is usedto estimatethe showermaximum, !#"%$ , heredefinedas the vertical depthof the point wherethe numberofchargedparticlesreachesits maximum. Thenumberof chargedparticlesat themaximum, X !#"%$ isalsoevaluated.

The estimationof the shower maximumis doneby meansof a 4-parameter fit to the Gaisser-

2Thestatisticalanalysisis madein a shower-per-shower basis.

CHAPTER 4. MANAGING AIRES OUTPUT DATA 79

Hillas function[29]3

X0aO�QNO`'T 8 X !#"%$�b `dc'`�e` !#"%$ cf` ehghi ��jlkhmOnVopjlqR srutwv-xzyh{ b ` !#"%$ cf`| g P `~}�`�eJ] (4.1)` !#"%$ , X !#"%$ , `�e and|

arethefreeparametersto beadjusted4. Noticethat X0a��NO`�e�T 8 , ,5 andthatX0aO�hNO`'T is takenas0 for `��` e .A weightednonlinearleastsquaresfit performedwith the aid of the very robust Levenberg-

Mardquardtalgorithm–asimplementedin the public domainsoftware library Netlib [10]– is doneafterthesimulationof every individual shower is completed.Thevaluesreportedin thesummaryfilecorrespondto theplain averageof all thefits with “reasonable”results(convergedfits). Thenumberof suchconvergedfits is alsoreported.

Tables section

The outputdatatableslisted in appendixC (page137) that areautomaticallycalculatedduring thesimulationscanbe totally or partially includedwithin the outputsummaryfile. An index of suchtablescanalsobeprintedusingthedirective TableIndex

ThePrintTablesdirective mustbeusedto includeoneor moretableswithin theoutputsummaryfile. Its syntaxis shown in thefollowing example:

PrintTables 1291 Options RM

This instructionordersAIRES to “print” table1291(longitudinaldevelopmentof all charged par-ticles) into the summaryfile. The optionsusedare: R, to list RMS errorsof the means,andM toincludemaximumandminimumdataasnumericalentries.For adetailedexplanationof thedirectivePrintTablesseepage130.

4.1.2 Expor ting data

An interestingfeatureof boththesummaryandthemainsimulationprograms,is thatthey areabletogenerateoutputfilescontainingany oneof thetableslistedin appendixC (page137).Let usconsider,

3Ourdefinitionof theGaisser-Hillas functioninvolvesverticaldepths.Someauthors,however, useslantdepthsinstead.Bothdefinitionscanbeusedto parameterizetheshower profile. Furthermore,noticethatin theplaneEarthapproximationboth “vertical” and“slant” forms areequivalent,provided the parametersareadequatelyinterpreted,that is, taking intoaccountthe factor �%�w�.� of equation(2.9). If theEarth’s curvatureis taken into account,the translationsbetweenverticalandslantquantitiesmustbedonenumerically(seepages17and214).

4In AIRES1.2.0a3-parameterfit is made.� is keptfixed,with anexternallygivenvalueof 70g � cm� . The4-parameterfitting algorithmcurrentlyusedincludessubstantialimprovementsthat incrementthegoodnessof thefits for a varietyofshower profileswhilst maintainingstablethefitting procedure.

5Thedepth � q refersto thepoint wheretheGaisser-Hillas function is zero,andis not equalandnot evennecessarilyrelatedto thedepthof thefirst interaction,noted�� in thismanual.


for instance,thefollowing IDL instructions:

Task mytaskSummary OffExport 1205 1211Export 1293 Option aExport 2001 Options dsExport 2791 2793 Options MLEnd

Heremytaskis a stringthatrepresentsanalreadyfinishedor currentlyrunningtask. TheSummaryOff directivesdisablesthesummaryfile. This is, of course,optional,but might beusefulwhentheuseris just interestedin creatingtablefiles.

Thefirst ExportTablesdirective (theabbreviatednamewill becorrectlyinterpretedby any of theAIRESmainprograms)indicatesthatall thetableswhosenumbersarein therange� 1205P 1211� mustbeexportedwith thedefault options. Looking at the listing in appendixC (page137), it comesoutthattheinvolvedtablesaretablesnumber1205,1207and1211.

The secondexport directive instructAIRES to export table1211with the option of listing theslant depthsof the observinglevels, that is, measuredalongthe shower axis (equation(2.8)). Bydefault (Optionr ) all atmosphericdepthslistedwithin exportedtablesareverticaldepths.

In the secondexport directive, the option string ds modifiesthe default settings. d indicatesthat the particlenumbersmustbe normalizedto particledensities,expressedin particles/m� ; andssuppressesthefile header(only thetableswill bewritten). This lastoptionmaybeusefulwhentheexportedfiles arereadby otherapplications(piped).Suppressingthefile header, however, mayleadto notunderstandablefiles,especiallyif they arenotprocessedat themomentthey areproduced.It isthereforerecommendedto alwayskeepsuchinformation;andit mustbealsotakeninto accountthatall theheaderlinesare“commentedout” by meansof a leadingcommentcharacterwhichdefaultsto“#”, but canbechangedby meansof thedirective CommentCharacter (seepage117).

In the last example,the energy distributions2791,2792and2793areexported. The option Mindicatesthatenergiesmustbeexpressedin MeV (thedefault is GeV);while L6 indicatesthatthecor-respondingdataarenormalizedto ��X��J�#�4�.�B� e � distributions. Thealternative option l correspondsto ��X��J��I�� normalization.

To processtheprecedingcode,it mightbeusefulto editasmalltext file containingthemandthenuse–for instance–thesummaryprogramto processit:

AiresSry < myfile.inp

Thefiles mytask.t1205, mytask.t1207, . . . , etc.,will becreated.If suchfiles alreadyexist, they willbeoverwritten.

If thesimulationsthatgeneratedthedatabeingprocesseswererunwith thePerShowerData op-tion Full (seesection3.3.6),thenit is possibleto exportsingleshowertablesby placingthedirective

6TheoptionslL werenotsupportedin AIRES 1.2.0.


ExportPerShower

togetherwith theExportTablesone(s).Returningto ourpreviousexample,if suchdirective is placedinsidethefile myfile.inp, thenfor eachoneof theexportedtables,thefiles

mytask.tnnnnmytasks0001.tnnnnmytasks0002.tnnnn]-]-]

will becreated,correspondingrespectively to theusualaveragetable,andthetablesfor shower 1, 2,etc.

4.1.3 The task summar y script file

Thetasksummaryscriptfile file (extension.tss) is a text file containinginformationaboutthemaininput andoutputparametersof the simulation,in a format suitablefor further processingby otherprograms.

Theformatof this file is very simple:Eachdataitem is writtenusingasingleline, in theformat

Keyword = value

Somecommentsareincludedto make thefile morehumanreadable.Thecommentlinesbegin withacommentcharacter(‘#’ or thecharactersetwith theCommentCharacterdirective).

In figure4.1a typical TSSfile is displayed.Someof therecordswerenot displayedfor brevity.Thefirst dataitemscorrespondto theversionof AIRES usedfor thesimulations,andtheunitscor-respondingto different quantitieswritten in the file. The generaldata,basicand additionalinputparameters,andmiscellaneoussectionscontainthe currentvaluesof all the input parameters.Thelastsectioncontainsasummaryof showerobservables.Usingoneline pershower, aseriesof showeroutputdatais displayed.The ShowerPerShowerKey line gives the key with the meaningof eachoneof thecolumnsof theshowerdatalines,startingwith theprimarycode(key PrCode) for thefirstitemaftertheequalsign,andcontinuinguntil completingall thefollowing items:

1 PrCode Primaryparticlecode2 PrEgy Primaryenergy3 Zenith Shower zenithangle4 Azim Shower azimuthangle5 X1v Verticaldepthof first interaction6 Xmaxv Verticaldepthof shower maximum7 Nmax Numberof particlesat shower maximum8 X0v Fittedparameter�e (vertical)of Gaisser-Hillas function(equation(4.1))9 Lambda Fittedparameter

|(vertical)of Gaisser-Hillas function(equation(4.1))

10 SofSqr Normalizedsumof squares(equation(D.1)) from thelongitudinalprofilefit11 FitRc Returncodeof thelongitudinalprofile fit


#### AIRES TSS --- version V.V.V#>>>#>>> This is AIRES version V.V.V (dd/Mmm/yyyy)#>>> (Compiled by . . .)#>>> USER: xxxxx, HOST: xxxxx, DATE: dd/Mmm/yyyy#>>>## TSS file for task mytask### Program and compilation parameters.#AiresVersion = V.V.V## Units#LengthUnit = mTimeUnit = secEnergyUnit = GeVDepthUnit = g/cm2AngleUnit = degMagneticFieldUnit = nT## General data#TaskName = mytaskTaskVersion = 0#TotalShowers = 3CompletedShowers = 3. . .. . . (Other general data). . .## Basic Input Parameters.#Site = Site00SiteLatitude = 0.000000SiteLongitude = 0.000000EventDate = dd/Mmm/yyyy#NumberOfDifferentPrimaries = 1PrimaryParticle = ProtonPrimaryParticleCode = 31. . .. . . (Other task input parameters). . .## Parameters relative to each shower#ShowerPerShowerKey = PrCode PrEgy Zenith Azim . . .#DataSh000001 = 31 350000. 0.00000 0.00000 . . .DataSh000002 = 31 350000. 0.00000 0.00000 . . .DataSh000003 = 31 350000. 0.00000 0.00000 . . .## End of tss file#

Figure 4.1.SampleAIREStasksummaryscript (TSS)file.


By default, AIRES doesnot createany tasksummaryscriptfile. Thedirective TSSFilemustbeusedto enablethis feature.

4.2 Processing compressed par tic le data files

Like other simulationsystems[1, 30], AIRES can produceoutput files containingdetailedinfor-mationabouttheparticlesgeneratedduring thesimulations.Thewell-known fact that thatdetailedinformationgenerateshugeamountsof datahasbeenespeciallytaken into accountin thedesignofAIRES,which includesanad hocdatacompressingalgorithmto save file space.

A detailedexplanationof the compressingalgorithm–a rathertechnicalmatter– is beyond thescopeof thismanual.Weshall limit ourselvesto briefly list its maincharacteristics:

Format. Thecompressedfiles areplain text files thatcanbegeneratedin any computerandcopiedandprocessedin any otherone.This is valid evenif themachinesdo not have thesameoper-atingsystemand/ordo notusethesamecharactercodes(for examplenon-ASCIImachines).

Organization. Thefiles containa headerwith datarelatedto its structureandtheconditionsof thesimulation.Theparticledatasectionrepresentsthebulk of thefile and,in general,therecordscorrespondingto any oneof thesimulatedshowersaredelimitedby “beginningof shower” and“end of shower” records.Thereis practicallyno limit in the numberof showersthat canbeincludedin asinglefile.7 Ontheotherhand,groupsof showerscanbesavedinto separatefiles,up to thelimit of storingeachshower in adifferentfile (seepage133).

Compressionrate. The datacompressionalgorithmsweredesignedto take profit of the physicalpropertiesof the quantitiesbeing stored. This involves information about lower and upperboundsfor avariable,possibilityof subtractingagivenfixedvalue8, etc.Precisionrequirementswerealso taken into account,imposinga minimum of five significantfiguresin mostcases.To give an ideaof the sizeof compressedrecords,let us considerthedefault groundparticlerecord(seebelow) whosefields are: Particle code,logarithmof the energy, logarithmof thedistanceto thecore,polaranglein thegroundplane,arrival time, C and F componentsof thedirectionof motion,andstatisticalweight. This recordthushasoneintegerfield andsix realones,andits lengthis 18 characters(bytes). This figureshouldbecontrastedwith a standardFORTRAN internalwrite statementwith singleprecisionfor realvariables,whichgenerates28databyteswhenwriting thesamefields.Takinginto accountthatsuchrecordsusuallyincludeadditionalformattingfields,thecompressionrateof AIRESalgorithmcomparedwith standardunformattedFORTRAN i/o shouldbelargerthan36%.

It is worthwhile mentioningthe the AIRES packageincludesa library of subroutines,namely,theAIRESobjectlibrary, which containsmany routinesto readandprocessthecompressedoutput

7It is possibleto storeup to 759375showersin a singlecompressedfile.8This refersto internaloperationswhich donotalterany user-level results.


files. Backwardscompatibility is alwaysensured:Old compressedfiles generatedwith any previousversionof AIRES canbereadnormallyusingthelibrary routines.

4.2.1 Customizing the compressed files

Two kindsof compressedfilesareimplementedin thecurrentversionof AIRES (2.6.0):

Ground particle file. (Extension.grdpcles) This file containsrecordswith dataof particlesthatreachedthegroundsurface.

Longitudinal tracking particle file. (Extension.lgtpcles) Compressedfile containingdetaileddatarelatedwith particlescrossingthepredefinedobservinglevels(seesection2.2.3).

Ground par tic le file

Therearethreebasictypesof datarecordsin thisfile: “Beginningof shower” record,“endof shower”recordandparticlerecord(alsoreferredasdefault record).The“externalprimaryparticle” and“spe-cial primarytrailer record”arealsodefined.Theselasttwo recordsareusedonly in connectionwiththespecialprimaryparticlesdescribedin section3.5(page70).

All theparticlerecordswrittenoutduringthesimulationof asingleshowerwill appearin thefileprecededby abeginningof shower record,andfollowedby thecorresponding“endof shower” one.

Thefieldsthatmake thebeginning(end)of shower recordarelistedin table4.1(4.2). Tables4.3and4.4 describethefieldsof thespecialprimary relatedrecords.In theseandin any otherrecords,thedatafieldscanbeclassifiedin integer andreal fields.

The fields containedin suchdelimiting recordsaccountfor generalair shower parametersorobservablesandwereincludedfor specialanalysistasks.

In thecaseof showersinitiatedby specialprimaryparticles(seesection3.5),the“Primary parti-cle” codeof thecorresponding“beginningof shower” recordwill notcorrespondto astandardparticlecode.Instead,thereturnedcodewill beanegative integerwith anabsolutevalueslightly smallerthan100000.9

In thosecases,the“beginningof shower” recordwill befollowedby aseriesof “externalprimaryparticle” records(onefor eachinjectedprimary particle). This seriesendswith a “specialprimarytrailer record”whichwill precedethedefault particlerecordswritten for thatshower.

Thefieldsincludedin thedefault records,associatedwith particledata,canbeselectedatcompiletime amongthe variousavailablealternatives. The installationconfigurationfile (seeappendixA)containsdetailedinstructionson how to selecttheparticlerecordoptions.

The mostrelevant physicalpropertiesof the groundparticlescanbe saved in the groundcom-pressedfile, namely,

Particle code. An integercodethatidentifiestheparticle.

9Thelibrary routinecrospcodeis theadequateoneto managesuchspecialparticlecodes.


Field Name Description

Integer 1 Primaryparticlecode Storesthecodeof theprimaryparticle.

2 Showernumber Shower number. By default, the firstshower is labeledwith thenumber1, buttheusercanmanuallysetthefirst showernumberby meansof the IDL directiveFirstShowerNumber (seepage121).

3–8 Startingdateandtime Six fields containing, respectively, theyear, month, day, hours, minutes andsecondscorrespondingto thebeginningof the simulationof the correspondingshower.

Real 1 Primaryenergy (GeV) (log) The logarithmof the primary particle’senergy.

2 Primaryzenithangle(deg) Thezenithangleof theprimaryparticle.

3 Primaryazimuthangle(deg) Theazimuthangleof theprimaryparti-cle.

4 Thinningenergy (GeV) The absolutethinning energy usedfortherespective shower.

5 First interactiondepth(g/cm2) Theverticaldepthof thepointwherethefirst interactiontookplace, � .

6 Centralinjectionaltitude(m) The H -coordinateof theprimary’s injec-tion point (seefigure2.1).

7 Globaltime shift (sec) Thetime �%e requiredfor a particlemov-ing along the shower axis at the speedof light, to go from theinjectionpoint tothegroundlevel.

Table4.1. Fieldscontainedin the“ beginningof shower” record of compressedparticle files.Thestructure of this record doesnotdependon thecompile-timeoptionselectedfor theparticle record.

Energy. Thelogarithmof thekineticenergy of theparticle.

Coordinates. ThepolarcoordinatesNO�P��#T of theparticleatground,measuredfrom theintersectionof theshoweraxiswith thegroundsurface. � is thedistanceto thecoreand � is theanglewithrespectto the C -axis.

Dir ectionof motion. The C and F components, p¡ , �¢ , of theunitaryvector £ which indicatestheparticle’s directionof motion. The p¤ componentmustbe negative for theparticlesreachinggroundbecausesuchparticlesmovedownwards.It canbecalculatedvia: E¤ 8 c¦¥ *�c' �¡ c' �¢ ] (4.2)



Integer 1 Showernumber Shower number (matching the showernumberof thecorresponding“beginningof shower” record).

2 Xmaxfit returncode Integer codereturnedby the ` !#"%$ andX !#"%$ fitting routinedescribedin section4.1(page77).

3–8 Endingdateandtime Six fields containing, respectively, theyear, month, day, hours, minutes andsecondscorrespondingto theendof thesimulationof thecorrespondingshower.

Real 1 Totalnumberof shower particles Totalnumberof particlesprocesseddur-ing the simulationof the correspondingshower.

2 Total numberof lost particles Total numberparticlesthatwentoutsidetheregionof interestfor thesimulations.

3 Numberof low energy particles Total numberof particleswhosekineticenergies fell below the correspondingthresholds.

4 Numberof particlesreachingground

Total numberof particlesthat reachedthe ground level, including also thoseparticles not saved in the compressedfile.

5 Total numberof unphysicalparticles

Numberof “particles”generatedby spe-cial procedures–like the splitting algo-rithm, for example–whichcannotbeas-sociatedwith physical particles. Thisnumberis generallyvery small.

6 Total numberof neutrinos Total numberof neutrinos( §J¨ , ©§J¨ , §�ª ,©§�ª ) generatedduring the simulationofthecurrentshower.

7 Particlestoonearto theshowercore

Numberof particlesthatwerenot savedin thecompressedfile becausethey weretoonearto theshower axis(seetext).

8 Particlesin theresamplingregion Numberof particlesthatwereprocessedwith theresamplingalgorithm(seetext).

Table4.2.Fieldscontainedin the“ endof shower” record of compressedparticlefiles.Thestructureof this record doesnotdependon thecompile-timeoptionselectedfor theparticle record.



Real 9 Particlestoo far from theshowercore

Numberof particlesthatwerenot savedin thecompressedfile becausethey weretoo far from theshower axis(seetext).

10 Showermaximumdepth(Xmax)(g/cm2)

Vertical depth of the point where thenumber of charged particles is maxi-mum, ` !#"%$ , obtainedfrom a fit to thesimulationdata(seesection4.1).

11 Totalchargedparticlesat showermaximum

Number of charged particlesat ` !#"%$ ,X !#"%$ , calculatedasexplainedin section4.1(page77).

12 Energy of lostparticles(GeV) Total energy of theparticlesof realfieldnumber2.

13 Energy of low-energy particles Total energy of theparticlesof realfieldnumber3.

14 Energy of groundparticles(GeV) Total energy of theparticlesof realfieldnumber4.

15 Energy of unphysicalparticles(GeV)

Total energy of theparticlesof realfieldnumber5.

16 Energy of neutrinos(GeV) Total energy of theparticlesof realfieldnumber6.

17 Energy lost in theair (GeV) Total amountof energy lost by contin-uousmediumlosses(ionization losses)dueto chargedparticlesmoving throughtheair.

18 Energy of particlestoonearto thecore

Total energy (in GeV) of theparticlesofrealfield number7. This field is not de-finedfor the longitudinaltrackingparti-cle file.

19 Energy of resampledparticles Total energy (in GeV) of theparticlesofrealfield number8. This field is not de-finedfor the longitudinaltrackingparti-cle file.

20 Energy of particlestoo far from thecore

Total energy (in GeV) of theparticlesofrealfield number9. This field is not de-finedfor the longitudinaltrackingparti-cle file.

21 CPUtime(sec) Amount of processortime requiredforthesimulationof thecurrentshower.

Table4.2. (continued)


Field Name Comment

Integer 1 Particlecode Storesthecodeof thecorrespondingpri-maryparticle.

Real 1 Energy (GeV) (log) The logarithmof thecorrespondingpri-maryparticle’s energy.

2 Directionof motion(x component) With respectto the AIRES coordinatesystem(seepage11).

3 Directionof motion(y component)

4 Directionof motion(z component)

5 X coordinate(m) Particle injection coordinate,with re-spectto the AIRES coordinatesystem(seepage11).

6 Y coordinate(m)

7 Z coordinate(m)

8 Injectiondepth(g/cm2)

9 Injectiontime (ns)

10 Particleweight Initial statistical weight of the corre-spondingparticle.

Table4.3. Fieldscontainedin the“ externalprimaryparticle” record of compressedparticlefiles.Thestructure of this record doesnotdependon thecompile-timeoptionselectedfor theparticlerecord.


Integer 1 Versionof externalmodule User-settableintegerin therange� ,QP�«J¬..®�«J¬¯� .Real 1 Totalnumberof primaries Totalnumberof primaryparticles.

2 Unweightedprimaryentries Unweightednumberof primaryentries.

3 Total energy of primary particles(GeV)

Totalenergy of primaryparticles(weighted).

Table4.4. Fieldscontainedin the“ specialprimarytrailer record” of compressedparticlefiles.Thestructure of this record doesnotdependon thecompile-timeoptionselectedfor theparticle record.


Field NameShort Normal Long

Integer 1 1 1 Particlecode

Real 1 1 1 Energy (GeV) (log)2 2 2 Distancefrom thecore(m) (log)3 3 3 Groundplanepolarangle(radians)– 4 4 Directionof motion(x component)– 5 5 Directionof motion(y component)4 6 6 Arrival timedelay(ns)5 7 7 Particleweight– – 8 Particlecreationdepth(g/cm2)– – 9 Lasthadronicinteractiondepth(g/cm2)

Table4.5. Fieldscontainedin theparticle recordsof compressedgroundparticlefiles.Thefieldnumbers for thedifferentparticle recordsselectableat compilationtime(seetext), namedshort,normal and long records,are tabulated.Noticethata givenfieldcanhavedifferentfieldnumbers.

Arri val time. Thesavedquantityis thearrival time delay �°c'� e , where � is theabsolutetime (mea-suredfrom thebeginningof theshower), and �\e is theglobal time shift describedin table4.1(page85).

Particle weight. Thestatisticalweightof theparticle(seesection2.3).

Creationdepth. Theverticalatmosphericdepthof thepointwheretheparticlewasinsertedinto thesimulatingprogram’s stacks.

Last hadronic depth. Theverticalatmosphericdepthcorrespondingto thelasthadronicinteractionsufferedby theparticleor by oneof its ancestors.

For eachoneof thesequantities,a correspondingrecordfield is defined. The completelist offieldsis placedin table4.5(page89). As mentionedpreviously, thereareseveralrecordformatseachoneincludingadifferentsubsetof all theavailablefields.

In contrastwith thebeginningof shower andendof shower records,a givenfield of theparticlerecordcanbeassigneddifferentfield numbers.As it will beseenbelow in this chapter, this doesnotaffect theuser’sprocessingof compressedfiles,whichcanbedoneindependentlyof thefield numberassignments.

TherearespecificIDL directivesthatcancontroltheparticlesthatareactuallysavedin thegroundparticlefile.

To startwith, let usconsiderthedirectivesRLimsFile andResamplingRatio, whosesyntaxis

RLimsFile grdpcles ± !°²´³ ± !#"%$ResamplingRatio µ^¶


grdpcles identifiesthe file the directive refersto and ± !°²´³ and ± !#"%$ representlengthspecifications( ,��·± !°²´³ ��± !#"%$ ). µ ¶ is a realnumber( µ ¶ }+* ).

Suchdirectives instruct AIRES to save unconditionallythoseparticleswhosedistancesto theshower axislie within theinterval � ± !°²´³ PR± !#"%$ � .

On theotherhand,all theparticleswhosedistancesto theshower axisaresmallerthan±Ve 8 ± !°²´³µ^¶ (4.3)

( ±Ve is, by definition,not larger than ± !°²´³ ) arenot includedin thegroundfile, but their numberandenergy arerecordedandthetotalsareincludedin the“endof shower record”(fields7, 9, 18,and20).

Finally, all the particleswhosedistances± to the shower axis lie in the interval � ± e PR± !°²´³ � areprocessedby a resamplingalgorithm which conditionallykeepsthe particlesaccordinglywith thefollowing rules: (i) “Nonnumerous”particles–like pions,nucleons,etc.–arealwayssaved. (ii) Forevery “numerous”particle–i.e.,gammas,electrons,positronsandmuons–in thementionedregion,theacceptanceprobabilityis10 ¸º¹ 8 b ±± !°²´³ g � ] (4.4)

(iii) Thestatisticalweightsof theacceptedparticlesareincreasedvia» D 8 »¸ ¹ P (4.5)

in orderto keepunbiasedthesamplingalgorithm.Thetotal numberandenergy of particlesthat fall within theresamplingarea,arerecordedin the

“endof shower record”(fields8 and19).The SaveInFile (SaveNotInFile) directive permits including (excluding) one or more particle

kinds into (from) thecompressedfile. Section3.2.5(page50) containsseveral illustrative exampleson how to usethem.

Noticethatby default,all particlekindsareenabledto besavedinto thegroundparticlefile.

Longitudinal trac king par tic le file

Thestructureof thelongitudinaltrackingparticlefile is very similar to thealreadydescribedgroundparticlefile: Both files have virtually the same“beginning of shower”, “end of shower”, “externalprimary particle”, and “special primary trailer” records;and thereare alternative formatsfor theparticlerecords.

For thatreason,it is highly recommendedto thereaderbefamiliar with thecontentsof theprevi-oussectiondescribingthegroundparticlefile beforeproceedingto readthepresentsection.Weshalllimit hereto briefly describeonly thoseaspectsthataresomehow differentin bothfiles.

The longitudinal tracking particle file containsrecordsstoring detailedinformation about theparticlesthat crossthedefinedobservinglevels. Sincetheobservinglevels aregenerallylocatedat

10Theexpressionof theacceptanceprobabilityis inspiredin a suggestionby P. Billoir [31].


Field NameShort Norm. Norm. Long Extra-

(a) (b) long

Integer 1 1 1 1 1 Particlecode2 2 2 2 2 Observinglevelscrossed

Real – 1 – 1 1 Energy (GeV) (log)– – 1 2 2 Directionof motion(x component)– – 2 3 3 Directionof motion(y component)1 2 3 4 4 Particleweight2 3 4 5 5 Crossingtime delay(ns)3 4 5 6 6 X coordinate(m)4 5 6 7 7 Y coordinate(m)– – – – 8 Particlecreationdepth(g/cm2)– – – – 9 Lasthadronicinteractiondepth(g/cm2)

Table4.6. Fieldscontainedin theparticle recordsof compressedlongitudinaltracking particle files.Thefieldnumbers for thedifferentparticle recordsselectableat compilationtime(seetext), namedshort, normal (a), normal (b), long andextra-longrecords,are tabulated.Noticethata givenfieldcanhavedifferentfieldnumbers.

altitudesthat includetheshower maximum,anddueto thefact thata singleparticlecancrossmorethanoneobservinglevel during its life, it is clearthat the longitudinalfiles canpotentiallybemuchlargerthantheaveragegroundparticlefiles.

For that reason,a specialeffort wasmadeto save asmuchspaceaspossible,andvariousrecordformatsweredefinedto allow theuserto selectjust thenecessaryfields.Therecordformatselectioncanbe doneduring installation,following the instructionsplacedin appendixA (page109). Table4.6(page91) listsall thedefineddatafieldsfor thedifferentdefault records.

The secondinteger field, named“Observinglevels crossed”containsinformationabouttheob-servinglevelstheparticlehascrossed,andsimultaneouslyaboutits directionof motion.

Let X0_ ( XZ_�¼�¬Q*-, ) bethenumberof definedobservinglevels.At acertainmonitoringoperation,a givenparticlecrossesseveralobservinglevels from level [½& to level [ ¾ ( [½¾ maybeequalto [½& ). Let E¤ be the H -componentof the particle’s directionof motion. If p¤¿)À, ( E¤¿�Á, ) the particlegoesupwards(downwards),andtherefore[Â&�}�[ ¾ ( [½&�¼�[ ¾ ).

All this informationis encodedin asingleintegernumbercalledthecrossedobservinglevelskey,Ã, definedby thefollowing equation:Ã 8 [½&�ÄÅ¬Q*VÆÇ[ ¾hÄÅ¬Q*VÆ � µ^ÈwÉ (4.6)

where µ^ÈzÉ 8ÁÊ * if ¤ )�,, if E¤Ë¼�, (4.7)


Thethreevariablesthatappearin theright handsideof equation(4.6)canbeeasilyreconstructedwhen

Ãis known (seepage100).

The real fields listed in table 4.6 (page91) aredefinedsimilarly to the correspondinggroundparticlerecordfields,with theexceptionof the C and F coordinateswhicharedefinedasfollows:

Coordinates. The N�C7PRF�T coordinatesare the Cartesiancoordinatesof the point wherethe particlecrossedthelevel [½& , measured from the intersection betweenthe shower axis and the cor-respondingobserving level’s surface.

Time delay. Definedas the difference��c·�u& where � is the particle’s absolutetime and �\& is thetime requiredfor a particlemoving alongtheshower axisat thespeedof light to go from theinjectionpoint to observinglevel [½& .

The IDL directivesRLimsFile, ResamplingRatio, SaveInFile andSaveNotInFile canbe usedwith longitudinalfiles to controlwhenaparticlemustbesavedor not. Thelasttwo directivesdo notpresentspecialdifficulties,andwork asexplainedin section3.2.5(page50).

On theotherhand,thedirectives11

RLimsFile lgtpcles ± !°²´³ ± !#"%$ResamplingRatio µ ¶

definethreeparameters,± !°²´³ , ± !#"%$ and µ ¶ , thatareusedto determinewhethera particlerecordmustbesavedor not. Therulesarethefollowing:

1. Let `�Y 8 ,Q] : `Ì°Ä�,Q]ÍÆÇ`M , where `Ì and `M are the vertical injection andgrounddepths,respectively.

2. For eachobservinglevel [ , [ 8 *JP-]-]-]�PRX _ , let

±-Ì 8ÎÏÏÏÏÏÏÐ ÏÏÏÏÏÏÑ, if ` � Ì _ ¼�`�YÒ `(� Ì _ c'`�Y`M�c'`�Y�Ó ± !°²´³ if ` Y �·` � Ì _ ��` M± !°²´³ if ` � Ì _ }�` M (4.8)

where `(� Ì _ is theverticaldepthof observinglevel [ ; andlet ±Ve\Ì 8 ±-Ì �Jµ ¶ .3. Any particlecrossingobservinglevels will not be saved in the longitudinalfile if oneof the

following conditionsis true:

(a) Ô CÇÔQ��±^e\Ì and Ô FºÔQ�·±Ve\Ì .(b) Ô CÇÔQ)�± !#"%$ or Ô FÕÔK)�± !#"%$ .

11Notice that the parametercontrolledby directive ResamplingRatio is global, that is, its last settingappliesto everyoneof thecompressedfiles in use.

CHAPTER 4. MANAGING AIRES OUTPUT DATA 93C and F aretheCartesiancoordinatesof theparticleat observinglevel [½& , measuredfrom theintersectionbetweentheshower axisandthecorrespondingobservinglevel.

4. Gammas,electrons,positronsandmuonscrossingobservinglevelsandverifying thetwo fol-lowing conditions

(a) Ô CÇÔQ��± !°²´³ and Ô FÕÔK��± !°²´³ .(b) Ô CÇÔQ)�± e\Ì or Ô FºÔK)�± e\Ì .

(in the samenotationof the previous point), will be conditionallykept, with probability andreweightingfactorgivenby equations(4.4)and(4.5),respectively.

5. All the particlesnot fulfilling the conditionsof the precedingpointswill be unconditionallysavedin thefile.

Theserulessetvaryinglimits for thezoneof excludedparticles.In thezoneneartheshoweraxis,all particlescrossingobservinglevelsplacedabove ` Y will besaved,thentheexclusionzoneenlargesproportionallyto the depthof the observinglevel, reachingthe value indicatedin the RLimsFiledirective at the grounddepth. Notice that `�Y divides the completeshower path (as measuredinatmosphericdepth)into two, upper-lower, 20%-80%,zones.12

The numberof definedobservinglevels affects the degreeof detail of the monitoring of thelongitudinalshower development,andsomeapplicationsusuallyrequirethatthis numberbeaslargeaspossible.Ontheotherhand,suchsettingmayleadto thegenerationof verybig longitudinalparticlefilessincea largenumberof datarecordsaregeneratedaslongaseveryparticlecrossestheobservinglevels. To overcomethis difficulty, AIRES includesa selectionmechanismto avoid includingin thecompressedfile theinformationrelatedwith all thedefinedobservinglevels. Considerthefollowingillustrative example:

ObservingLevels 100SaveInFile lgtpcles e+ e-RecordObsLevels NoneRecordObsLevels 1RecordObsLevels 4RecordObsLevels 10 90 10RecordObsLevels Not 20

The first directive setsthe numberof observinglevels to 100, andthe secondoneenablesparticlesaving in the longitudinal particle tracking file. In this caseonly electronsand positronswill berecorded(Notice that the longitudinalfile is disabledby default, andthereforeit is necessaryto useunlessone SaveInFile instructionto enableit). The default action is to recordparticlescrossinganyof thedefinedobservinglevels,andtheremaininginstructionsareplacedto overridethis defaultsetting. Thedirective RecordObsLevels None eliminatesall the definedobservinglevels from the

12Thepresentfiguresmodify the40%-60%zonesusedin AIRES 2.0.0or earlier.


setof levelsto betakeninto accountto save particlerecordsinto thecompressedfile. Theactionsofthe instructionsthat follow are,respectively: Mark level 1 for recordingparticlescrossingit; idemlevel 4; idem all levels from 10 to 90 in stepsof 10 levels; unmarklevel 20. The resultingsetofmarkedlevelsis Ö�×JØuÙhØV×-ÚQØSÛJÚQØuÙ�ÚQØSÜJÚhØSÝ.ÚQØzÞ�ÚhØSßJÚhØSà.ÚKá .4.2.2 Using the AIRES object librar y

TheAIRESobjectlibrary is a setof routinesdesignedwith themainpurposeof providing adequatetoolsto analyzethedatasavedin thecompressedoutputfiles.

AppendixD (page144) explainsin detail the contentsof the library andhow to useit. In thissectionsomeillustrative examplesarepresented.

From now on we are going to assumethat the AIRES file is being processedby a program,provided by the userandsimilar to the demonstrationprogramsthat are includedwith the AIRESsoftwaredistributions.

We aregoing to useFORTRAN in our examples,but this is not a restrictionsincethe AIRESlibrary includesroutinesfor a C interface,which allow the C userto fully exploit the library’s re-sources.

Output par tic le codes

Every analysisprogrammustbegin with a call to routineciorinit . This routinessetsup theenviron-mentwherethelibrary routinescanwork adequately.

This routinepermitssettingthe particlecodingsystemthat the userwantsto work with. It ispossibleto selecteither the AIRES codingsystemalreadydescribedin section2.2.1(page20), orotherusualcodingsystems.Thecodingsystemsknown by AIRES 2.6.0arethefollowing:

1. Aires internalcoding.

2. Aires codingfor elementaryparticlesanddecimalnuclearcodes( âäã�×-Ú.Ú�å ).

3. ParticleDataGroupcodingsystem[32], extendedwith decimalnuclearcodes( âÅã�×-Ú.æ�å ).

4. CORSIKA simulationprogramparticlecodingsystem[30].

5. GEANT particlecodingsystem[33].

6. SIBYLL [6] particlecodingsystem,extendedwith decimalnuclearcodes( âÅãç×-Ú.Ú�å ).

7. MOCCA-styleparticlecodes[1], extendedto matchall AIRES particles13.

Thecodescorrespondingto elementaryparticlesarelistedin table4.7.

13Actually, MOCCA doesnotuseparticlecodes.Instead,particlesareidentifiedby types(1 gamma,2 electron,3 muon,etc.) andcharge ( è , éëê , etc.). Our MOCCA-stylecodesemulatethis codingsystemgeneratingparticlecodesby joiningthesignof thechargeandtheparticletype.


Particle CodesAIRES PDG CORSIKA GEANT SIBYLL MOCCAì × í.í × × × ×î^ï í ð¦×.× í í í íîJñ ð�í ×.× Û Û Û ð�íò�ï Û ð¦×VÛ Ü Ü Ù ÛòÇñ ð�Û ×VÛ Ý Ý Ü ð�Ûó ï Ù ð¦×VÜ ß.Ý ß.Ý íJÚ ×-Úó ñ ðôÙ ×VÜ ß�Þ ß�Þ ð�íJÚ ð¦×-ÚõJö Ý ×Ví Ý.Ý Ù ×VÜ Ú÷õ ö ð�Ý ð¦×Ví Ý�Þ ð ×VÝ Úõ�ø Þ ×zÙ Ý.ß Ù ×^Þ Ú÷õ ø ð�Þ ð¦×zÙ Ý.à ð ×Vß Úõ�ù ß ×VÝ Ù Ù ð Ú÷õ�ù ð�ß ð¦×VÝ ð ð ð ÚúÕû ×-Ú ×.×.× Þ Þ Ý Üú ï ×.× íQ×.× ß ß Þ Ùú ñ ð¦×.× ð�íQ×.× à à ß ðôÙü ûý ×Ví ÛQ×-Ú ×VÝ ×VÝ ×Ví ×Víü ûþ ×VÛ ×VÛJÚ ×-Ú ×-Ú ×.× ×VÛü ï ×zÙ Û.íQ× ×.× ×.× à ×.×ü ñ ð¦×zÙ ð�Û.íQ× ×Ví ×Ví ×-Ú ð¦×.×ÿ ×VÜ í.íQ× ×^Þ ×^Þ í.í ×zÙ� ÛJÚ íQ×.×Ví ×VÛ ×VÛ ×zÙ Ý÷� ð�ÛJÚ ð�íQ×.×Ví í.Ü í.Ü ð¦×zÙ ð�Ý� ÛQ× í.íQ×Ví ×zÙ ×zÙ ×VÛ Þ÷� ð�ÛQ× ð�í.íQ×Ví ×VÜ ×VÜ ð¦×VÛ ð�Þ

Table4.7. Elementaryparticlecodescorrespondingto several commonlyusedcodingsystems.Theroutinesthat processAIREScompressedoutputfilesallow theuserto selectanyoneof thesecodingschemes.


Opening existing files

Oncethe properenvironmentis setup by meansof the initializing routine, the systemis readytoopenany existing compressedfile. Theopenroutineopencrofile will usetheheaderinformationtoinitialize the internal variablesthat permit processingthe different fields definedfor the file. Thefollowing exampleillustrateshow to openafile:

program samplecharacter*80 mydir, myfileinteger channel, irc. . .call ciorinit(0, 1, 0, irc). . .call opencrofile(mydir, myfile, 0, 10, 4, channel, irc). . .

myfile andmydir arecharacterstringscontainingrespectively thefile nameandthedirectorywhereitis placed.Theintegerargument“10” indicatesthatthelogarithmicfieldsaregoingto betransformedinto decimallogarithms.channel is anoutputparameteridentifying theopenedfile; it shouldnot besetby thecallingprogram.

It is importantto remarkthat this call will transparentlyopenany compressedfile, regardlessofits typeor format(groundparticleaswell aslongitudinaltrackingparticlefiles in all their variants),theAIRESversionusedto write it and/orthemachineusedwhenwriting it.

Getting inf ormation about the file

Theheadersof thecompressedfilesaredividedinto two parts:Onepartcontainingthedefinitionsofthefile’s datarecordsandanothersectionwith informationaboutthesimulationsthatoriginatedthefile.

The file definitionsarespecificto eachopenedfile, and thereforethe systemmuststorethemseparatelyfor eachoneof thefiles thataresimultaneouslyopen.

The other information,however, is of global character, andso the availabledataalwayscorre-spondsto thelastopenedfile. Thesedataaresupersededeachtime opencrofile is called.

Routinecroheaderinfo printsa summaryof this globalinformationwhile croinputdata0 copiessomeof thosedata into arraysto make them available to the user(seepage154) and crotaskidreturnstasknameinformation.Functionsgetinpint, getinpreal, getinpstring andgetinpswitch (seepages176–179)allow to obtainother input dataitems not returnedby croinputdata0. getglobalcanbecalledto retrieve informationaboutglobalvariablesthatweredefinedduringthesimulations.idlcheck returnsinformationabouttheIDL instructionsthatwerevalid whenthefile wasgenerated,andcrofileversionandthisairesversion returnversioninformationthatmightbeusefulwhenreadingcompressedfileswrittenwith old AIRESversions.

In somespecialapplicationsit is necessaryto accessinformationthat canbe storedonly in theinternal dumpfile. In thesecases,it canbe helpful to invoke the routine loadumpfile right after


openingthe correspondingcompressedfile, and then usesomeof the routinesdumpinputdata0,dumpfileversion, etc.,to accessthementioneddata.

The structureof any alreadyopenedfile canbe printedcalling routinecrofileinfo which printsa list of the different recordsdefinedfor the correspondingfile and the namesof the fields withinrecords.It is alsopossibleto load into arrayssuchinformationby meansof routinecrorecstrut inorderto make it availableto theanalysisprogram.

Reading the data recor ds

Onceafile is open,it remainspositionedat thebeginningof thecompresseddatasection.Fromthenon, thefile canbesequentiallyreadusingroutinegetcrorecord:

okflag = getcrorecord(channel, indata, fldata, altrec,0, irc)

getcrorecord returnslogical data,which in this casearestoredin thelogical variableokflag. Thereturnedvalueis “ true” if thereadingoperationwascompletedsuccessfully, “ false” otherwise(endof file, I/O error, etc.).

ciochannshouldbethesameintegervariableusedwhenopeningthefile; it identifiesthefile tobeprocessed.

ir c is anintegerreturncode.If okflag is “f alse”,thenthereturncodecontainsinformationabouttheerrorthatgeneratedtheabnormalreturn,asexplainedin page172.For successfulreadoperations,ir c indicatestherecordtypethathasbeenjust readin: 0 for thedefault particlerecord,1 (2) for the“beginning (end)of shower” record,etc. At thesametime, the logical variablealtrec distinguishesbetween“alternative” (nondefault) records(true), from default ones(false).

Thedatastoredin thedifferentfieldsof therecordis retrievedby meansof thearraysindata andfldata. Both aresingleindex arrays,containingintegeranddoubleprecisiondata,respectively. Thedataitemsstoredin thesearraysdoesvarywith thekind of file beingprocessedandthetypeof recordthatwasscanned.In all cases,theroutinewill automaticallysettherelevantelementsof thesearraysaccordinglywith the logical definitionof therecord,regardlessof thephysicalstructureof it whichremainsabsolutelyhiddenat theuser’s level.

To fix ideas,let ussupposethata groundparticlefile with normalparticlerecordsis beingpro-cessed. Every time ir c is zero (default record), the integer and real dataarrayswill containtheelementslistedin table4.5(page89), thatis

indata(1) � Particlecode

fldata(1) � Energy (GeV) (log)fldata(2) � Distancefrom thecore(m) (log)fldata(3) � Groundplanepolarangle(radians). . .fldata(7) � Particleweight


For different returncodes,the numberof assignedarrayelementsmay be different,aswell astheirmeanings;but in all casessuchdataitemswill besetaccordinglywith thecorrespondingrecordsequence(tables4.1,4.2,etc.).

In orderto make theanalysisprogramssimplerandmorerobust, a specialroutinehasbeenin-cludedin theAIRES library to automaticallysettheadequatefield indicescorrespondingto a givenrecordof acertaincompressedfile, asillustratedin theexampleof figure4.2.

The outstandingcharacteristicof this pieceof codeis that the elementsof arraysindata andfldata arenot referenceddirectlyusingnumericindices,but by meansof integervariableslike icodefor instance(seefigure4.2).

Thoseindex variablesaresetby meansof routinecrofieldindex. Theargumentsrequiredby thisroutine include: (i) The identificationof the file (channel). (ii) The recordtype, coincidentwiththe returncodesof getcrorecord alreadymentioned. In this example0 for the default recordand2 for the “end of shower” record. (iii) The first charactersof the field name. Fieldsare identifiedby their names,providing thereforeabsolutetransparency to the fact that the orderandnumberoffields may changewith the file beingprocessed.The next argumentof crofieldindex is setto 4 toforce the programto stop in caseof ambiguousor erroneousfield specification,thus providing avery safeprocessingenvironment. (iv) The outputargumentdatype returnsinformationaboutthedatatype correspondingto the specifiedfield, asexplainedin page149. In the particularcaseoflongitudinalparticletrackingfiles, it is generallyconvenientto usetheroutinegetlgtrecord in placeof getcrorecord. A completedescriptionof getlgtrecordcanbefoundin page181;this routinemustbeusedjointly with getlgtinit.

Closing files and ending a processing session

TheAIRES library routinessupportsimultaneousprocessingof morethanonecompressedfile. Sev-eralcompressedfilescanbeopenedat thesametime,eachoneidentifiedby thecorrespondingchan-nel integervariable.

The openedfiles can be closedusing two alternative procedures(seepage145): (i) Routinecioclose1closesindividual files. ciocloseclosesall thecurrentlyopenedfiles.

Routineciocloseshouldbeusedonly if theprocessingsessionwill continueafterclosingall files.To finish an analysisprogramin an orderedfashionusethe routineciorshutdown. This procedureperformsall therequiredtaskstoproperlysetdown theprocessingsystem,includingacall to cioclose.

Other operations

Therearemany other routinesincludedin the AIRES library that provide useful tools for specialanalysistasks.Suchroutinesareexplainedin detail in appendixD (page144),we shall limit heretoabrief presentationof themostrelevantones:

Counting records. Routinescrorecinfo andcroreccountcountthedatarecordscontainedwithin acompressedfile.


program sample. . .integer datype, irc, icode, idist, inearinteger indata(30)double precision fldata(30)integer particlecodedouble precision logdistance, numberofnear. . .call ciorinit(0, 1, 0, irc)call opencrofile(mydir, myfile, 0, 10, 4, channel, irc). . .

icode = crofieldindex(channel, 0, ’Particle code’,4, datype, irc)

idist = crofieldindex(channel, 0,’Distance from the core’,4, datype, irc)

inear = crofieldindex(channel, 2, ’Particles too near’,4, datype, irc)

. . .

okflag = getcrorecord(channel, indata, fldata, altrec, 0,irc)

if (irc .eq. 0) thenparticlecode = indata(icode)logdistance = fldata(idist). . .

else if (irc .eq. 2) thennumberofnear = fldata(inear). . .

end if. . .

Figure 4.2.Processingcompresseddatafiles,anexampleillustrating howto setfield indicesautomatically.


Repositioning. Routinecrorewind repositionsan alreadyopenedfile at the beginning of the datasection. Routinescrorecnumber and crogotorec, usedjointly, permit accessingthe datarecordsin arbitraryorder.

Fastscanningof a file. Routinecrorecfind findsthenext appearanceof a recordof a giventype(tolocateshower headers,for example). getcrorectype returnsthe type of the next record,andregetcrorecord re-readsthecurrentrecord.

Longitudinal tracking file utilities. Routinecrooldatareturnsbasicinformationaboutthepositionsof theobservinglevelsdefinedfor thesimulations;while olcoord returnsthecoordinatesof theintersectionsbetweentheobservinglevelsandtheshoweraxisandolv2slantevaluatestheslantdepthscorrespondingto eachobservinglevel. Routinesolcrossedandolcrossedudecodethecrossedobservinglevels key definedin equation(4.6), returningthe variables�� , �� and ��(seesection4.2.1). The logical functionolsavemarked permitsdeterminingwhetheror not agivenobservinglevel is recordedinto acompressedfile.

Specialprimary utilities. Besidesthespecificroutinesdesignedtoprocessspecialprimaryparticles,describedin detail in section3.5, theAIRES library includesalsosomeauxiliary routinesthatareusefulto obtaindataaboutthespecialprimariesthatweredefinedat themomentof creatingthecompressedfile thatis beinganalyzed.crospcodeandcrospmodinfo areexamplesof suchprocedures.

Miscellaneousroutines. Thelibrary containssomeotherroutinesthanmaybeusefulin certainap-plications,for examplethepseudo-randomnumberutilities raninit , urandom,urandomt, andgrandom; Gaisser-Hillas functionrelatedroutines:fitghf , ghfpars, ghfx, ghfin; atmosphericdepthutility routinesline xslant; etc.

The AIRES object library is continouslyevolving, so additionalprocedureswill be surely in-cludedin futureAIRES versions.

Chapter 5

The AIRES Runner System

Productionsimulationtasksusuallyrequirelargeamountsof computertime to complete,andin suchcasestheuserrisksloosingall thesimulationrun if thesystemgoesdown beforethetaskis finished.To avoid this inconvenientsituation,the AIRES simulationsystemprovides a specialauto-savingmechanismthatpermitssplitting thesimulationjob into smallruns.In caseof abnormalinterruption,thesimulationscanberestartedat thepoint they werewhenthelastauto-saving wasperformed.

As explainedin chapter3 (page45), a simulationtask may requireseveral invocationsof thesimulationprogramif the auto-save mechanismis enabled.If this is donemanually, the usermustcontrolthesequenceof instructionsneededto completethesimulations.To easethemanagementofsuchsequentialseriesof processes,asetof scriptsweredevelopedwith thecapabilityof automaticallylaunchingthecorrespondingjobs.Thesescriptsarepartof theAIRESRunnerSystem(ARS), designedasasetof interactive proceduresto managecomplex simulationstasks.

The AIRES RunnerSystemworks only on UNIX platforms1, andprovides tools for input filechecking,sequentialandconcurrenttaskprocessing,event logging,etc. This chapteris devotedtopresentsomeexamplesthatwill helptheuserto getfamiliar with theRunnerSystem.

Therearemany parametersthatmodify thebehavior of theAIRESRunnerSystem.Mostof themareuser-settableandtheirdefinitionstatementsareplacedwithin theARSinitializing file .airesrc. InstandardAIRES installations,this file is placedin theuser’s homedirectory.

5.1 Checking input files

In section3.2.2(page46), the IDL directivesCheckOnly andTrace wereusedto instructAIRESsimulationprogramsto scanagiveninputfile, reportonits contentsandstopwithoutactuallystartingthesimulations.

TheARS command

airescheck -t myfile.inp

1TheremaybesomeincompatibilitieswhenrunningARScommandsin clustersemploying “afs” file systems.

101

102 CHAPTER 5. THE AIRES RUNNER SYSTEM

will invoke Air eswith the sameinput asdisplayedin page47. The -t qualifier is placedto enabletyping theinput linesaslong asthey arescanned.

Thereareadditionalqualifiersacceptedby thiscommand,for example:

airescheck -tP -p AiresQ myfile.inp

The -p qualifier overridesthe default simulationprogramusedto processthe input file, andthe Pswitch indicatesthat the outputmustbe printed insteadof being typedat the terminal. The printcommandto usecanbesetmodifying the .airesrc initializing file.

5.2 Managing sim ulation tasks

Oncetheinput file hasbeenchecked,thesimulationscanbestarted.Thecommand

airestask myfile

will first checkthat file myfile.inp2 exists, andthenwill createan entry in the correspondingARSspool.Finally, aireslaunchwill beexecuted.

Theaireslaunchscriptwill detectthatthereis a taskpendingcompletionandsowill prompttheuserto startthesimulations.In caseof positive answer, thesimulationprogramwill bestartedwiththecorrespondinginput,andwill berepeatedlyinvokedif necessaryuntil thetaskis completed3. Allthoseoperationsarecompletelyautomatic,no furtheruserinterventionis normallyrequired.

If therearemorethanonetaskto beprocessed,they canbespooledatany momentafterlaunchingthefirst simulations.Thecommand

airestask my other file

will make anew spoolentrywhichwill bequeuedafterthefirst one.Executionof this taskwill startassoonasthepreviousoneis finished.Thereis no limit in thenumberof tasksthatcanbequeuedintheARSspools.

At any momentduringthesimulations,it is possibleto inspecttheevolution of thespooledtasksby meansof theARScommandairesstatus.

In theprecedingexamples,thedefault simulationprogram(whichnormallyis theAir esprogram)will beused.Therearetwo alternativesto overridethedefault specification:(i) Modify thedefaultprogramsettingof theinitializationfile .airesrc. (ii) Usethe-p qualifierof theairestaskcommand:

airestask -p AiresQ yet another file

Air esQis thenameof a variabledefinedwithin theinitialization file, which indicatestheexecutableprogramthatcontainsa link to theQGSJEThadronicpackage.4

2airestaskfirst assumesa default extension.inp for theinputfile name,andasa secondalternative, triesto find thefilewhosecompletenameis asspecifiedin theinputparameter.

3Thesimulationprogramcommunicateswith thescriptvia a file thatcontaininformationaboutthestatusof thesimu-lations.

4Use-p Air esSto explicitly specifythesimulationprogramlinkedto theSIBYLL hadroniccollisionmodel.

CHAPTER 5. THE AIRES RUNNER SYSTEM 103

5.2.1 Canceling tasks and/or stopping the sim ulations

Everyspooledtaskcanbecanceledby meansof thecommandairesuntask, for example:

airesuntask my other file

will erasethesecondspooledtaskof theprecedingsection.If theairesuntaskcommandis invokedwith no parameters,thenit will prompttheuserto canceleachoneof thespooledtasks.

It is not recommendableto remove the spool entriescorrespondingto tasksthat arecurrentlyrunning. In suchcasesit is betterto first stop the simulationprogram,andwait until the AIRESRunnerSystemshutsdown.

The simulationprogramcanbe stoppedwith the ARS commandairesstop, which generallyisinvoked with no arguments. This script originatesan orderedshutdown of the simulations,whichincludesanupdateof theinternaldumpfile, andmaytakeupto severalminutesto effectively interruptthesimulations.Thecommandairesstatuscanbeusedto monitorthestatusof thesystemduringthisprocess.

On theotherhand,a currentlyrunningsimulationcanbeimmediatelyabortedby meansof com-mandaireskill. In this casethecorrespondingprocessesarekilled without any previousauto-savingoperation.

Stoppedsimulationscanalwaysberestartedusingaireslaunch.

5.2.2 Performing custom operations between processes

Every time a process5 ends,the ARS checksfor the existenceof a executablescript namedAfter -Process(casesensitive!), first in thecurrentworkingdirectory,andthen–if not found–in thedefaultdirectoryof theuser’s account(HOME directory).If thefile is found,it is executed.

Thecompletecommandline usedwheninvoking theAfterPr ocessmacrois thefollowing:

AfterProcess spool tn msg rc trial totsh lastsh prog

where

spool is thespoolidentification.

tn is thetaskname.

msg is a messagestring comingfrom the simulationprogram. Normally it takes the valuesEnd-OfTask or EndOfRun, indicatingif thecurrenttaskwasor not finished,respectively. Othervaluesarealsopossibleandcorrespondto abnormalsituations.

rc is a numericparameter, takingthevalue2 if therun hasbeenstoppedusinganAIRES.STOPfile(commandairesstop).

5Seesection3.1(page45).


trial is anumericvariablecountingthenumberof trials for thecurrentrun. Generallytakesthevalue1, but in certaincircumstances,for examplewhenrelaunchingAIRES aftera systemcrash,itcantake largervalues.

totsh is thetotal numberof showersfor thecurrenttask.

lastsh is thelastcompletedshower.

prog is theinstructionusedto invokeAIRES,whichincludesthefull nameof thesimulationprogramusedin thelastrun.

This powerful ARS optionmakesit possiblefor theuserto performoperationsof almosteverykind after endingthe processes.Of course,a certaindegreeof expertisewith UNIX systemsmayberequiredin certaincases.Typical examplesof operationsthatcanbedoneusingthis facility are:File movementaftercompletionof tasks(for exampleto massive storagesystems),alertsof any typeaboutconditionsof thesystem,like full disks,etc.

On return,theAfterPr ocessscriptcancommunicatewith theARS via theexit code.If it is zerothenprocessingwill continuenormally, otherwisetheARS will senda mail notifying theabnormalreturncodeandthenwill stop. If it is necessaryto restartthesimulations,it canbe doneusingtheARScommandaireslaunch.

Thefollowing shellscriptis avery simpleexampleof an“after process”macro:

#!/bin/sh#if[ $3 = EndOfTask ]then## This code will be executed only after ending a task.#mv $ Ö 2 á .grdpcles /mysafeplace

fiexit 0

Noticethatnoactionwill betakenup to theendof a task.Whenever thishappens,thecorrespondinggroundparticlefile is movedto anotherdirectory. Thecommandexit 0 ensuresnormalreturncode;exit n with n � Ú meansanabnormalexit andin thiscasethesimulationswill bestopped.

Similarly asin thecaseof theAfterPr ocessmacro,theARSsystemwill searchfor aBeforePro-cessmacro,right beforeinvoking thesimulationprogram.Theexistenceof theBeforeProcessmacrois checked in theworking directory,andin theuser’s account(HOME) directory(in thatorder). Ifthefile is found,it is executed.


Thecompletecommandline usedwheninvoking theBeforeProcessmacrois thefollowing:

BeforeProcess spool tn trial ifile prog

where

spool is thespoolidentification.

tn is thetaskname,or UNKNOWN if thetaskis not initializedyet.

trial is anumericvariablecountingthenumberof trials for thecurrentrun. Generallytakesthevalue1, but in certaincircumstances,for examplewhenrelaunchingAIRES aftera systemcrash,itcantake largervalues.

ifile is thenameof theinputfile to beusedwhenrunningthesimulationprogram.

prog is theinstructionusedto invokeAIRES,whichincludesthefull nameof thesimulationprogramusedin thenext run.

After completingexecutionof theBeforeProcessmacro,theARS checksthecorrespondingre-turncode,continuingwith thenext steponly if it is zero.

5.3 Concurrent tasks

In many casesit is necessaryto simultaneouslyprocessmorethanonetask.Systemshaving morethanoneCPUand/orclustersof machinessharingthesamefile system,areexamplesof suchsituation.

The AIRES RunnerSystemprovidescertaintools designedto work undersuchcircumstances.Thekey ideais to definemorethanonespool,andassignonespoolto eachprocessingunit, eitheraCPUor amachineinsidethecluster.

In theprecedingexamples,theairestaskcommandwasinvokedwithoutspoolspecification.Thedefault spool is usedin caseof missingspecification,and that is what wasactuallydonein thoseexamples.

In thestandardconfigurationthereare9 predefinedspools,namedrespectively “1”, “2”, . . . , etc.Spool“1” is thedefault spool6. Thecommand

airestask -s 2 myfile

will createa spoolentry placedin spool“2”. The userwill be promptedto start the simulationsifthereis currentlynoactivity relatedwith thatspool.Thecommand

airesstatus 2

6TheARSincludesalsothecommandsmkair esspoolandrmair esspoolwhichallow theuserto respectively createanddeletespooldirectories.


will reporton thesimulationsthatarerunningatspool“2”.

In the following interactive session,it is illustratedhow to launchthreesimultaneoustasks(itis assumedthat the machinepossessesvariousCPU’s which canbe automaticallyassignedto thelaunchedprocesses):

cd directory1aireslaunch -s 1 task1

. . .

cd directory2aireslaunch -s 2 task2

. . .

cd directory3aireslaunch -s 3 -p AiresQ task3. . .

It is mostimportantthat theworking directoriesof differenttasksbe alsodifferent: Concurrentsimulationprogramsrunningwith thesameworking directorymaygenerateconflictswhencommu-nicatingwith theARS scripts. This fact is stressedby meansof the cd commandsof the example,wheredir ectory1, dir ectory2 anddir ectory3 mustbedifferentdirectoryspecifications.

Noticealsothat the third spoolingcommandmakesuseof analternative simulationprograminorderto performa differentkind of simulation. Alternative programsmay alsobe necessarywhenrunningsimulationsonclusterssharingthesamefile systembut madewith noncompatibleplatforms.In thosecasesit is necessaryto have different executablemodulesfor eachplatform. Oncesuchmodulesareavailable, it is possibleto changethe default programscorrespondingto the differentspoolsby meansof suitablemodificationsto the .airesrc initialization.

Thedetailsabouthow to make the AIRES RunnerSystemwork in complex operatingenviron-mentsarerathertechnicalandgo beyond thescopeof this manual.Sucha job requiresnormallyagooddegreeof expertiseon UNIX systems.

5.4 Some commands to manage dump file data

Chapter4 (page77)explainsin detailtheoperationsneededto retrieve datastoredwithin theinternaldumpfile in either its binary or ASCII versions. Someof themarefrequentlyusedandgenerallyinvolve very similar sequencesof instructions. A typical exampleis to export oneor more tablescorrespondingto analreadyfinishedtask.

The ARS includesa shell script that canbe helpful in thosecases.Considerfor examplethecommand(underUNIX)

airesexport mytask 1001 1205 to 1213


Its actionis to invoke theAIRESsummaryprogramwith thefollowing input

Summary OffTaskName mytaskExportTable 1001ExportTables 1205 1213End

generatingtext files for tables1001,1205,1207,1211and1213(seeappendixC).In somecasesit maybenecessaryto specifyotherparameters,like in thefollowing example

airesexport -w idfdir -O LM -s mytask 2501

This commandwill generatesingle shower tables(enabledby the -s qualifier) as well as averageones. The optionsLM correspondto �� û�� distributions with energies expressedin MeV(seesection4.1.2),andthestringfollowing the-w qualifier(idfdir ) indicatesthedirectorywheretheIDF and/orADF files arelocated(The global directoryaccordinglywith the definitionsof section3.3.2).

5.4.1 Conver ting IDF binar y files to ADF por table format.

ADF files wereimplementedfor AIRES version2.0.0,andto have themwritten by the simulationprogramsafter a task is completed,it is necessaryto explicitly enablethemby meansof the IDLdirective ADFile. The (binary) IDF is alwaysgenerated,regardlessof the input settingsand/ortheversionof AIRES used.

Of course,the IDF storesall thedataassociatedwith both input parametersandoutputobserv-ables,andis enoughfor any kind of analysisprovided theuseralwaysworkswith compatiblecom-puters.But this may not be the casewhena personor groupis working at different locations.Forsuchcases,aportablefile formatis neededandtheADF becomesessentialto enabledataanalysisinnon-compatibleworkstations.

If theADF wasnot generatedduringthesimulations,or if thesimulationswereperformedusinga versionof AIRES previous to version2.0.0, it must be createdmanually. The currentAIRESdistribution includesanIDF to ADF convertingprogram,whosedefault nameis Air esIDF2ADF.

This programcanbe useddirectly. It is just necessaryto invoke it (no argumentsneeded)andanswerto thepromptsthatwill beappearing.

On the otherhand,the ARS includesa specialshell script that permitsconverting files withoutcalling Air esIDF2ADF manually. Let us illustratehow to usethis commandwith anexample.Sup-posein a certainplacetherearesomeIDF files thatneedto beconvertedto ADF format. TheUNIXcommand

idf2adf taskname1 taskname2 taskname3

will searchfor thefiles taskname1.idf, taskname2.idf, etc.,andwill call Air esIDF2ADF asmanytimesasnecessary, to createthe portablefiles taskname1.adf, taskname2.adf, etc. Of course,theold IDF fileswill remainunchanged.


This scriptwill work well in mostcases.However, theremight bespecialsituationswhereit isnecessaryto useAir esIDF2ADF manually, for examplewhenthe IDF file is renamedwith a newnamenotendingwith “.idf ”.

Appendix A

Installing AIRES and maintainingexisting installations

As mentionedin section1.3 (page9), every AIRES distribution is currentlypacked in a singlecom-pressedUNIX tar file. In this appendixit is assumedthat thesoftwaredistribution wassuccessfullydecompressedandtarexpanded.

A.1 Installing AIRES 2.6.0

In UNIX platforms,theinstallingprocedureis quitesimple:Almosteverythingis doneautomatically.Thekey pointsto take into accountare:

(a) A Unix shellscriptdoinstall is provided.This scriptwill install thesoftwareautomatically.

(b) Thefile config containsall thecustomizablevariables.You mustedit it beforeinvoking doin-stall

(c) Therewill betwo maindirectories:

1. Installation root directory (hereinafternamedIr oot), which is the directorywherethedistribution file wasdownloaded(thatis, thedirectorycontainingthedoinstall script).

2. Airesroot directory (hereinafternamedAr oot), which is the highestlevel directoryforthe installedfiles. You will needto specifyAr oot. For standard,personalinstallation,thedefault (creatinga directorynamedairesin your homedirectory)will beOK. Noticethatthe Ir oot andAr oot directoriesmayor maynotbethesamedirectory(Do notworryaboutthis: Theinstallationprogramwill manageevery caseproperly.).

(d) Your accountmust have accessto a FORTRAN 77 compiler (normally, commandsf77 orfort77), and in somecasesto a C compiler (commandscc, gcc, etc.); and thesecompilersmustbeplacedin oneof thePATH directories(in otherwords,if youtypeatyour terminal,say,f77, themachinewill take f77 asa known command).If thecompilersarenot in thePATH

109

110 APPENDIX A. INSTALLING AIRES AND MAINTAINING EXISTING INSTALLATIONS

youwill have to entertheirabsolutelocationmanuallyin theconfigfile (Our recommendation,however, is to ensurethatthecompilersarein thePATH. It is somethingnotdifficult to achieve.If you do not know how to proceedor whatwe arespeakingabout,thenaskyour local UNIXexpert).

(e) Thesimulationprogramusesscratchfiles for internaldatapaging. Thescratchspaceneededfor a run dependson the input parametersand the size of the internal particle stacks. Forultra-high-energy, hard-thinnedshowers(Primaryenergy greaterthan ×-Ú �� eV, primaryenergyover thinning energy ratio greaterthan ×-Ú�� .), and for a stacksize of 5 MB (the default), aminimum of 15-20MB scratchfile spacewill be neededduring the simulations.This figurecanbe more than100 MB for very “heavy” simulations. If you want to reducethe scratchspacerequirements,thenyou will have to lower the stacksize,modifying the correspondingparameterin file config.

A.1.1 Installation procedure step by step

1. Ensurethat you have write permissionon both Ir oot andAr oot directories,and in all theirsub-directories.

2. cd to Ir oot, andedit thefile config. Setall thevariablesaccordinglywith theguidelinesthereinplacedandwith yourneeds.It is mandatoryto selectoneandonly oneplatform. If noneof thespecifiedplatformsmatchyour machine,thenyou shouldtry using“the mostadequateone”,continuingwith theinstallationprocedureandseeingwhathappens.Save thefile andleave theedit sessionwhenfinished.

3. Enterthecommand

doinstall 0

if you areinstallingAIRES for thefirst time,or

doinstall 1

if you areupgradingyour currentinstallation(This is thecasefor thoseusersthatarealreadyemploying apreviousversionof AIRES.Notethatyoumust not eraseany existinginstallationof AIRESbeforecompletingtheupgrade.).

This procedurewill install thesoftwareusingthedatayou setin step2. This may take someminutesto complete. A messagewill be typed at your terminal indicating whetherthe in-stallationwas successfulor not. If you get any error message(s),you shouldcheckall therequirementsdescribedpreviously, in particularpoints (d) and (1). Try also modifying theconfigfile.

APPENDIX A. INSTALLING AIRES AND MAINTAINING EXISTING INSTALLATIONS 111

4. Typethecommand(casesensitive)1

Aires

to seeif the programis running and is in your searchpath. You shouldseetyped at yourterminalsomethinglike thefollowing text2:

>>>>

>>>> This is AIRES version V.V.V (dd/Mmm/yyyy)

>>>> (Compiled by . . . . .

>>>> USER: uuuuu, HOST: hhhhhhh, DATE: dd/Mmm/yyyy

>>>>

> dd/Mmm/yyyy hh:mm:ss. Reading data from standard input unit

whereV.V.V indicatesthecurrentversionof AIRES (2.6.0)andgoestogetherwith thereleasedate.Typex andpress ENTER! to leave theprogram.

If step3 endedsuccessfullyandyou fail to run the program,it is likely that the AIRES bindirectoryis not in your environmentsearchpath(Unix environmentvariablePATH). In somesystemsyouneedto log outandlog in againto makeeffectiveany PATH change.If youcannotplacetheAIRES bin directoryinto youraccount’s PATH, thenaska Unix expertto do thatforyou. Onceyou aresurethatthedirectoryis in thesearchpath,andif theproblemstill persists,checkif the executablefile Air es exists. If it doesnot exist that meansthat step3 wasnotsuccessfullycompleted.Do not continuewith thenext stepuntil yousucceedwith thisone.

5. cd to your HOME directoryandverify thepresenceof afile named.airesrc.

Normally it is not necessaryto changeanything in this file, but the needmay appearin thefuture,speciallyif youdecideto usetheUNIX scriptsthatareprovidedto helprunningAIRES(seechapter5).

6. If you completedsuccessfullythesesteps,thesoftwareshouldbeproperlyinstalled.

7. After successfullycompletingthesestepsyou candeletethe files correspondingto old ver-sionsof AIRES.Suchfilesareplacedwithin theAroot directory. For example,directory1-2-0containsAIRES1.2.0files,etc.

1ThenameAir escanbechangedmodifyingadequatelytheconfigfile. If thisnamewaschanged,thentheusersuppliednamemustbetypedin placeof thedefault one.

2Youshouldalsoobtainasimilaroutputif youinvoketheAIRES/QGSJETsimulationprogramAir esQinsteadof Air es.

112 APPENDIX A. INSTALLING AIRES AND MAINTAINING EXISTING INSTALLATIONS

A.2 Recompiling the sim ulation programs

In many casesit may be necessaryto recompilethe simulationprogramsafter having successfullyinstalledtheAIRES system.Someexamplesof suchsituationsare:" Somecompilationparameterswerenot setaccordinglywith the userneeds;or the required

configurationis no moretheonesetupat themomentof installingthesoftware." It is necessaryto installAIRES in different(not compatible)platformssharingthesamedirec-tory tree." It is necessaryto createmorethanoneexecutableprogram,eachonecompiledwith differentcompilationparameters.As an exampleof this case,considerthat the numberand kind ofrecordsthatarewritten in thecompressedparticlefilescanbecontrolledby meansof compila-tion parameters(seesection4.2.1),andthat it is requiredto have theexecutablesfor differentfile formats.

Theargumentsrecognizedby thedoinstall executablescriptallow theuserto easilyperformthedifferentoperationrequiredin caseslike theonespreviously enumerated.

Thegeneralsyntaxof doinstall is:

doinstall ilev [ cfext ]

ilev is anintegerrangingfrom 0 to 4 indicatingthe“level” of installation:

0 Completeinstallationof the AIRES system.Necessaryonly wheninstalling AIRES for the firsttime.

1 Upgradeof anexisting installation,makingtheinstalledversionthenew currentversion.

2 Recompiling. All thesimulationprogramsandthesummaryprogramarecompiledandlinked.TheAIRES objectlibrary is rebuilt.

3 Relinking. New executablesfor all thesimulationprogramsandthesummaryprogramarecreatedusingtheexistingobjectfiles.

4 Rebuilding thelibrary. TheAIRESobjectlibrary is rebuilt usingtheexistingobjectfiles.

cfext is anoptionalargument.It is a characterstring indicatingthatanalternative configurationfilemustbeusedto setthe installationparameters.If cfext is no null, thenthefile config.cfext is usedinsteadof thedefault configfile usedwhencfext is not specified.

To performdifferentcompilation/installation jobs,it mightbeusefulto haveseveralconfigurationfiles. For example,the config file is first copiedto a new config.short file. Then config.short iseditedchangingthefollowing parameters:(i) The format for bothgroundandlongitudinaltracking

APPENDIX A. INSTALLING AIRES AND MAINTAINING EXISTING INSTALLATIONS 113

compressedfiles is set to “short”. (ii) The nameof the executableprogramAir es is changedintoAir es sht. Finally thecommand

doinstall 2 short

is executed.Thiswill generateseveralnew executableprograms,namely, Air es sht, Air es shtQ,Air es shtS16, andAir es shtQ99, which will be capableof producingcompressedfiles with shortformatparticlerecords.

Appendix B

IDL reference manual

Both the main simulationprogramsAir esandAir esQ, andthe summaryprogramAir esSryuseacommonlanguageto receivetheuser’s instructions.This languageis calledInputDirectiveLanguage(IDL), andcurrentlyconsistsof some70 differentinstructionsto setsimulationparameters,controltheoutputdata,etc. In thissectionwe list, alphabeticallyordered,all AIRES 2.6.0IDL directives.

The IDL directivescanbewritten usingno specialformat,with onedirective per line (thereareno “continuationlines”, but eachline cancontainup to 176characters).Thedirectivesstartwith thedirective namefollowedby thecorrespondingparameters.All the“words” thatform asentencemustbeseparatedby blanksand/ortabcharacters.

All directivesarescanneduntil eitheranEnd directive or anendof file is found.Mostdirectivescanbeplacedin any orderwithin theinputstream.TheInput directive permitsinsertinginstructionsplacedin separatefiles letting the user to conveniently organizecomplex input datasets. Inputdirectivescanbenested.

Dynamic(canbe setevery time the input file is scanned),static (canbe setonly at taskinitial-ization time) and hidden1 (associatedwith rarely changingparameters)directives are respectivelymarkedasd, s, h. Namesin typewriter or boldface font referto keywords,while namesin ital-ics refer to variableparameters.Underlined partsof keywordsrefersto shortestabbreviations: Notunderlinedcharactersareoptional.Expressionsbetweensquarebrackets([ expression]) areoptional,while alternativesarewritten in thefollowing way: Ö alt 1 # alt 2 á . To specifyangles,lengths,times,energies,atmosphericdepths,magneticfields,etc.,it is requiredto give two fieldsseparatedby blankspace:

number unit

number is a decimalnumberandunit is a characterstringrepresentingthephysicalunit usedin thespecification.All the valid units arelisted in table3.1 (page49). Additionally, time specificationsmay be of the form: [ number hr ] [ number min ] [ number sec], wherenumber representsafloatingpoint number.

1Hiddendirectivesareconnectedto parametersthatseldomneedto bemodified.They arenot printedin theinput datasummary, unlesswereexplicitly setor a full listing modewasenabled.Notice that this only affectsoutputdataprinting:All otherdirective propertiesremainunchanged.

114

APPENDIX B. IDL REFERENCE MANUAL 115

B.1 List of IDL directives.

#

Commentcharacter. For every scannedinput line, all charactersplacedafter the commentcharacter‘#’ areignored.

&Syntax: &label

IDL label.Labelsareusedby directivesRemark andSkip. The& mustbethefirst non-blankcharacterin theline, andall charactersafter label aretreatedasa comment.label is anonnullstringwhichcancontainany characterexcludingblanksandthecommentcharacter#.

AddSiteSyntax: AddSite name lat long height

(d) Appendinga new site to theAIRESsite library. name is a stringhaving no morethan16characters,andmustbe different to all the previously definedsitesincluding the predefinedentrieslisted in table 3.2 (page64). Site namesare casesensitive. lat and long are anglespecificationsdefiningrespectively thegeographiclatitudeandlongitudeof thesite. lat (long)mustbein therange $4ð�àJÚ�%JØSàJÚ�%'& ( $4ð ×VßJÚ�%JØV×VßJÚ�%(& ). height is a lengthspecificationdefiningthesite’s altitudeabove sealevel. Thedirective Site permitsto selectalreadydefinedlocations.

AddSpecialParticleSyntax: AddSpecialParticle pname module [ parstring ]

(d) Adding a new definition to the list of specialparticles.pnameis a string having no morethat 16 charactersthat uniquely identifiesthe specialparticle being defined. module is thenameof theexecutablemoduleassociatedto thespecialparticle. The file modulemustexistin thecurrent“workingdirectory”or in oneof thedirectoriesthatwerespecifiedwith directiveInputPath. Every time a new shower with “primary” pnamestarts,the modulemodulewillbeexecutedby themain simulationprogramto generatea list of (standard)primaryparticlesthatwill be theactualshower primaries.Section3.5 (page70) containsa detaileddescriptionabouthow to build andusesuchkind of modules. parstring is an optionalparameterstring(cancontainembeddedblanks)thatis (portably)passedto theexternalmodule.

ADFileSyntax: ADFile [ ) On * Off + ]Default: ADFile is equivalentto ADFile On

ADFile Off is assumedin caseof missingspecification.

(d) If ADFile On is specified,thenanASCII dumpfile will begeneratedupontaskcompletion.The ASCII dumpfile (ADF) is a portableversionof the internaldumpfile (IDF) that canbe

116 APPENDIX B. IDL REFERENCE MANUAL

transferredamongdifferentplatforms.

AirA vgZ/ASyntax: AirAvgZ/A numberDefault: AirAvgZ/A 0.5

(s,h)Setsthevalueof theaverageratio ,.-(/ for air.

This directive belongsto themodel-dependentIDL instructionsetandmaybechangedor notimplementedin futureversionsof AIRES.

AirRadLengthSyntax: AirRadLength numberDefault: AirRadLength 37.1

(s,h)Setsthevalueof theradiationlengthfor air, expressedin g- cm0 .This directive belongsto themodel-dependentIDL instructionsetandmaybechangedor notimplementedin futureversionsof AIRES.

AirZeffSyntax: AirZeff numberDefault: AirZeff 7.3

(s,h)Setsthevalueof theeffective atomicnumber, for air.


AtmosphereSyntax: Atmosphere labelDefault: Atmosphere 1

(s)Switchesamongdifferentatmosphericmodels.label is anintegerlabelingthemodelsavail-able.Thesemodelsarecurrentlytwo: (1) Linsley’s standardatmospheremodel. (2) Linsley’smodelfor theSouthPole.

BracketsSyntax: Brackets ) On * Off +

Brackets [ On ] ob cb [ ec ]Default: Brackets On )1+ &

(d) Controlsthebehavior of thevariablereplacementalgorithmusedwhile scanningtheinputfile. Whenthefeatureis disabled(BracketsOff ) the input linesarenot scannedto searchfordefinedvariablesto bereplaced.WhenBracketsOn is in effectandtherearedefinedvariables,thenvariablesubstitutionis performedwhenit corresponds.Theactivevariablenamesmustbe


enclosedusingthecurrentbrackets,which canbechangedusingthis directive. Theargumentsob, cb, andec correspond,respectively, to the openingandclosingbrackets,andthe bracketescapecharacter. Thesesinglecharactervariablesmustbedifferent,andcanbespecifiedwiththesamerulesthatapplyfor theargumentof theCommentCharacterdirective.

CheckOnlySyntax: CheckOnly [ ) On * Off + ]Default: CheckOnly is equivalentto CheckOnly On

CheckOnly Off is assumedin caseof missingspecification.

(d) WhenCheckOnly is enabled,thesimulationprogramreadsandprocessall the input datanormally, performstheinternalconsistency checksandthenexits without startingthesimula-tions.Thisdirective is usefulfor input file debugging.

CommentCharacterSyntax: CommentCharacter ) char * nnn +Default: Thedefault commentcharacteris ‘#’

(d) Theplaintext filesproducedwith theExportTablesdirectivecanhaveheadingandtrailinglines.All theselinesstartwith acommentcharacterin theirfirst column.Thedefault commentcharacter(‘#’) is normally OK, but if the Export ’ed files could be usedas input of anotherprogram(a plotting utility, for example)which recognizesa differentcommentcharacter;insuchcasesthe CommentCharacter directive permitssettingthis mentionedcharacter. charcan be any single character(with no quotes). Alternatively, the commentcharactercan bespecifiedby meansof its ASCII decimalcode,expressedin theform of a three-figure numbernnn (This permitsusingnon-printablecommentcharactersaswell asresettingthe commentcharacterto ‘#’).

DateSyntax: Date fpyear

Date year month dayDefault: Thecurrentdateat themomentof invoking theprogram.

(s) This directive setsthedateassumedfor thesimulations.Thedateis usedat themomentofevaluatingthegeomagneticfield by meansof the IGRF model(seesections2.1.5and3.3.4).Settingthedatemaybenecessarywhenperformingsimulationswith thepurposeof analyzinga certainair shower eventreportedby anexperiment.Thedatecanbespecifiedeitherasthreeintegers(yearmonthday) or afloatingpoint numberwith theformat“year.part of the year”.

DelGlobalSyntax: DelGlobal var

(d) Deletesanalreadydefinedglobalvariable.SeealsodirectivesImport andSetGlobal.


DielectricSuppressionSyntax: DielectricSuppression [ ) On * Off + ]Default: DielectricSuppression is equivalentto DielectricSuppression

On

DielectricSuppression On is assumedin caseof missingspecification.

(s,h)Switchto include/excludethedielectricsuppressioneffect from theLPM algorithms[19,25] for the caseof electronor positronbremsstrahlung.The effect is enabled by default.Disabling it may leadto non realisticair shower simulations. If LPMEffect Off is in effect(seepage125),thenthedielectricsuppressionis alwaysdisabled.


DumpFileSyntax: DumpFile

Reservedfor futureuse.

ElectronCutEnergySyntax: ElectronCutEnergy energyDefault: ElectronCutEnergy 80 KeV

(s) Minimum kinetic energy for electronsandpositrons.Every electronhaving a kinetic en-ergy below this thresholdis not taken into accountin the simulation;positronsareforcedtoannihilation.energymustbegreaterthanor equalto 80keV.

ElectronRoughCutSyntax: ElectronRoughCut energyDefault: ElectronRoughCut 900 KeV

(s) Electronsandpositronsarenot followed usingdetailedcalculationswhentheir energy isbelow theonespecifiedby meansof this directive. This meansthatseveralprocessesarenottaken into account,for exampleCoulombscattering.energymustbegreaterthanor equalto45 keV.


ELimsTablesSyntax: ELimsTables minenergy maxenergyDefault: ELimsTables 10 MeV emax

emaxis themaximumbetween10 TeV and 24365�798;:�<>=@?�AB<DC .(s) This directive definesthe energy interval to use in the energy distribution tables(his-


tograms). Eachenergy distribution histogramconsistsof 40 logarithmic bins startingwithminenergy(lower energy of bin 1) andendingwith maxenergy(upperenergy of bin 40).

EMtoHadr onWFRatioSyntax: EMtoHadronWFRatio ratioDefault: EMtoHadronWFRatio 88

(s,h)Ratiobetweentheelectromagneticandhadronicthinningweightfactors.This instructionpermitssettingthe ratio /FEHG of equation(2.23). ratio mustbeequalor greaterthan1. Thedefault valueof 88, adjustedtaking into accountthe resultsof representative simulations,isnormallyadequate.

EndSyntax: End

(d) End of directive streamfor the currentinput file. The file is no morescannedwhenthisdirective is found. If End is notpresent,thefile is entirelyscanned.

ExitSyntax: Exit

x

(d) Theprogramis stoppedwithout takingany furtheraction. This directive is usefulto endaninteractive session.

ExportPerShowerSyntax: ExportPerShower [ ) On * Off + ]Default: ExportPerShower is equivalentto ExportPerShower On

ExportPerShower Off is assumedin caseof missingspecification.

(d) This directive affectsonly thosetaskssimulatedwith thePerShowerData Full option(seepage128). If ExportPerShower On is specified,thena set of plain text files (onefile persimulatedshower) will be written for all the tablesselectedfor exporting (seedirective Ex-portTables). Eachone of these“single shower” tablescontainsthe valuesadoptedby thecorrespondingobservable in the respective shower. The normal tablecontainingthe averageover showersis alsoexported,andis notaffectedby thisdirective.

ExportTablesSyntax: ExportTables mincode[ maxcode] [ Options optstring]

ExportTables Clear

Default: No tablesareexportedby default.

(d) Tableswhosecodesrangefrom mincodeto maxcodeareselectedfor exportingasplaintextfiles. If maxcodeis not specified,it is takenequalto mincode. Thetablecodesareintegers.A


completelist of availabletables(morethan180) is placedin appendixB, or canbe obtainedwith directives Help tables and/orTableIndex. The Clear option permitsclearingthe listof exportedtables,thus overriding all the previous ExportTables directives. opstring is astringof charactersto setavailableoptions:s (h) suppress(include)file header;x (X) include“border” bins ascomments(within the data);U do not include “border” bins; r (d) normal(density)lateraldistributions;L (l) distributionsnormalizedas IJ-�ILK�M�N�O�P ( IQ-�I�KSR ); r (a) expressatmosphericdepthasvertical (slant)depths;K , M , G, T, P, E, expressenergiesin keV, MeV,. . . , EeV. Thedefault optionsare:hxrG .

ExtCollModelSyntax: ExtCollModel [ ) On * Off + ]Default: ExtCollModel is equivalentto ExtCollModel On

ExtCollModel On is assumedin caseof missingspecification.

(s) Switchto enable/disabletheexternalhadronicinteractionsmodel:SIBYLL [6] in thecaseof theAir esprogramor QGSJET[7] for theAir esQmainsimulationprogram.


ExtNucNucMFPSyntax: ExtNucNucMFP [ ) On * Off + ]Default: ExtNucNucMFP is equivalentto ExtNucNucMFP On

ExtNucNucMFP On is assumedin caseof missingspecification.

(s,h) Switch to enable/disablecalculationof meanfree pathsfor nucleus-nucleuscollisionsvia theexternalhadronicinteractionsmodel: SIBYLL [6] in thecaseof theAir esprogramorQGSJET[7] for theAir esQmainsimulationprogram.

If the switch is set to Off then the nucleus-nucleusmeanfree pathsare evaluatedusing anAIRESbuilt-in procedure.In thiscasethemeanfreepathsareobtainedby scalingproperlythecorrespondingproton-nucleusmeanfreepath.

This directive hasno effect on simulationsperformedusing the old versionsof SIBYLL orQGSJET(programsAir esS16or Air esQ99, respectively), wherethe nucleus-nucleusmeanfreepathsarealwaysevaluatedby meansof thebuilt-in procedure.



FileDir ectorySyntax: FileDirectory dopt directoryDefault: Theoutputandscratchdirectoriesdefault to thecurrent(working)directory. The

globalandexport directoriesdefault to thecurrentvalueof theoutputdirectory.

(d) Thisdirectivesetstheoutputfile directories2. doptis acharacterstringthatcantakeany oneof thefollowing values:All, Output, Global, Export, or Scratch. Thesealternativespermitsettingall theAIRES directoriesdefinedin section3.3.2(page60). TheoptionAll canbeusedto simultaneouslysetthe“output” (compressedfile), “global” and“export” directories.directory is a characterstring not longer than 94 charactersthat must be recognizedby theoperatingsystemasavalid directory.

FirstShowerNumberSyntax: FirstShowerNumber fshowernoDefault: FirstShowerNumber 1

(s) A positive integer in therange T�U�V'5�7�W�X�5�7ZY indicatingthenumberto beassignedto thefirstsimulatedshower. Theshower numberis usedin tables5000to 5513,andin the“beginningofshower” and“end of shower” compressedfile records(for detailsseechapter4).

ForceInitSyntax: ForceInit [ ) On * Off + ]Default: ForceInit is equivalentto ForceInit On

ForceInit Off is assumedin caseof missingspecification.

(d) If ForceInit is enabled,thena new task is startedat the beginning of every process.IfthecorrespondingIDF file exists, thenthetaskversionis increaseduntil anunusedversionisfound.Thisdirective is usefulfor debuggingpurposes.

ForceLowEAnnihilationSyntax: ForceLowEAnnihilation optDefault: ForceLowEAnnihilation Normal

ForceLowEAnnihilationwith no specificationis equivalenttoForceLowEAnnihilation Always.

(s,h)Directive to controltheactionto takewhenprocessinga low energy particlethatcananni-hilatewith its respectiveanti-particle.ThevariableoptcantakethevaluesAlways, Never, orNormal. Thefirst two alternativescorrespond,respectively, to thecaseswherethelow energyparticleswill alwaysbeforcedto annihilationor bediscardedwithoutproducingany secondaryparticle.In the(default) Normal optiontheactionto take for annihilatinglow energy particlesdependson the particlecut energy andmass:If the cut energy is less(greater)thanthe rest

2Theold (AIRES 1.4.2andolder)syntaxis no longersupported.


massthentheparticleis (is not) forcedto annihilation.

ForceLowEDecaysSyntax: ForceLowEDecays optDefault: ForceLowEDecays Normal

ForceLowEDecayswith nospecificationis equivalentto ForceLowEDecaysAlways.

(s,h) Directive to control the action to take when processinga low energy unstableparticlethatcandecayinto otherparticles.Thevariableopt cantake thevaluesAlways, Never, orNormal. Thefirst two alternativescorrespond,respectively, to thecaseswherethelow energyparticleswill alwaysbeforcedto decaysor bedicardedwithoutproducingany secondaryparti-cle. In the(default)Normal optiontheactionto takefor decayinglow energy particlesdependson theparticlecut energy andmass:If thecut energy is less(greater)thantherestmassthentheparticleis (is not) forcedto decays.

ForceModelNameSyntax: ForceModelName modselDefault: No modelnamecheckis performedwhenthisdirective is notused.

(s) This directive allows theuserto forcethata giveninput datasetwill beprocessedwith thesimulationprogramlinkedwith theexternalcollisionpackagespecifiedwith modsel. Currentlymodselcanbeoneof (casedependent!)SIBYLL or QGSJET.


GammaCutEnergySyntax: GammaCutEnergy energyDefault: GammaCutEnergy 80 KeV

(s) Minimum energy for gammas.Every gammaray having anenergy below this thresholdisnot takeninto accountin thesimulation.energymustbegreaterthanor equalto 80keV.

GammaRoughCutSyntax: GammaRoughCut energyDefault: GammaRoughCut 750 KeV

(s) Gammaraysarenot followed usingdetailedcalculationswhentheir energy is below theonespecifiedby meansof this directive. This meansthat severalprocessesarenot taken intoaccount,for examplepairproduction.energymustbegreaterthanor equalto 45 keV.



GeomagneticFieldSyntax: GeomagneticField [ ) On * Off + ]

GeomagneticField stg[ inc [ dec] ] [ Fluctuations fluc ]GeomagneticField [ On ] Fluctuations fluc

Default: GeomagneticField Off whenthereis noSite specification;GeomagneticField On otherwise.

(s) Settingthegeomagneticfield manuallyand/orenablingmagneticfluctuations.stgmustbea valid magneticfield strengthspecification,and inc anddecareanglespecifications.Suchfieldscorrespondrespectively to thegeomagneticfield strength,F, andto theinclination,I, anddeclination,D, anglesdefinedin section2.1.5(page19). Whenoneor moreof suchparametersareenteredby meansof theGeomagneticFielddirective, they overridethe respective valuesthatarecalculatedautomaticallyusingtheIGRFmodel[8], asexplainedin section3.3.4(page64). Thefluctuationspecificationfluc adoptsthreedifferentformats:(i) Absolute:In this casefluc representsa(positive)magneticfield strength.(ii) Relative:fluc adoptstheformatnumberRelative, andrefersto theratiobetweentheactualfluctuationstrengthandtheaveragevalueofthemagneticfield. (iii) In percent: fluc adoptstheformatnumber% . numbercorrespondstoarelative specificationmultipliedby 100.Theeffectof magneticfield fluctuationsis explainedin section3.3.4(page64).

GroundAltitudeSyntax: GroundAltitude altdepth

GroundDepth altdepthDefault: Thealtitudeof thesitecurrentlyin effect.

(s) Groundlevel altitude. altdepthcanbeeithera lengthspecification(rangingfrom 0 to 112km) or anatmosphericdepthspecification(rangingfrom 0 to 1033g/cm0 ).

HelpSyntax: Help [ ) * * tables * sites + ]

help [ ) * * tables * sites + ]? [ ) * * tables * sites + ]

(d) Theactionof theHelp directive is to typea brief summaryof IDL directives,outputdatatables(histograms)or sitesdefinedin theAIRES sitelibrary. Help * givesa full IDL directivelist, includingall “hidden” directives.The? form is equivalentto thecombinedactionof HelpandPrompt On


ImportSyntax: Import [ ) Dynamic * Static + ] varnameDefault: No environmentalvariablesareimportedby default.

(d) Importingenvironmentvariables.Theoperatingsystemenvironmentvariablevarnameisimportedandstoredasanactive variablethat caneitherbe usedwithin the IDL input streamor passedto thecompressedoutputfiles or specialprimary modules.The Dynamic qualifier(default) indicatesthe dynamiccharacterof the correspondingvariable. This meansthat thevaluecurrentlypassedto theexternalmodulesis modifiedeachtime AIRES is invoked for agiven task. On the otherhand,Static variablesaresetat the first invocationof AIRES; andfurthersettingshave no effect.

InjectionAltitudeSyntax: InjectionAltitude altdepth

InjectionDepth altdepthDefault: InjectionAltitude 100 km

(s) Primaryinjectionaltitude. altdepthcanbeeithera lengthspecification(rangingfrom 0 to112km) or anatmosphericdepthspecification(rangingfrom 0 to 1033g/cm0 ).

InputSyntax: Input file

(d) File file is insertedin theinputdatastream.Input directivescanbenested.Thesearchpathfor locatinginputfilesincludethe“workingdirectory”(seesection3.3.2)andall thedirectoriesthatwerespecifiedwith directive InputPath.

InputListingSyntax: InputListing [ ) Brief * Full + ]Default: InputListing is equivalentto InputListing Brief

InputListing Brief is assumedin caseof missingspecification.

(d) Datarelatedto hiddeninputdirectivesarenotprintedin theoutputsummaryfile unlessthecorrespondingvariableswereexplicitly setor InputListing Full wasspecified.

InputPathSyntax: InputPath [ Append ] [dir1[:dir2[:...] ] ]Default: No pathbesidesthe“workingdirectory” is setby default.

(d) Modifying thedirectorysearchpathfor thefiles includedwith the Input directive and/orexecutablemodulesreferredby AddSpecialParticle instructions.This directive canbe usedmultiple timesif required.Differentsearchdirectoriescanbespecifiedin a singleinvocationseparatingthemwith colons(:) with no embeddedblanks. The keyword Append indicates


thatthespecifieddirectory(ies)mustbeappendedto theonesalreadyinserted.If InputPath isinvokedwith noarguments,thenthesearchpathis cleared.

LaTeXSyntax: LaTeX [ ) On * Off + ]Default: LaTeX is equivalentto LaTeX On

LaTeX Off is assumedin caseof missingspecification.

(d) If LaTeX On is specified,then the outputsummaryfile is written usingthe LATEX wordprocessorformat.Otherwiseit is writtenasaplain text file. Whenthisoptionis enabled,aTEXfile taskname.tex is createdsimultaneouslywith thesummaryfile.

LPMEffectSyntax: LPMEffect [ ) On * Off + ]Default: LPMEffect is equivalentto LPMEffect On

LPMEffect On is assumedin caseof missingspecification.

(s,h)Switchto include/excludetheLandau-Pomeranchuk-Migdaleffect [24, 19] from theelec-tron-positronandgammapropagatingalgorithms.Theeffect is enabledby default. Disablingit may lead to non realisticair shower simulations. If LPMEffect Off is in effect, then thedielectricsuppressionis alsodisabled(seepage118).


MaxCpuTimePerRunSyntax: MaxCpuTimePerRun ) time * Infinite +Default: MaxCpuTimePerRun Infinite

(d) This directive setsthemaximumCPUtime for individual runs,beinga run theprocessingchunk that goesbetweentwo consecutive updatesof the internaldumpfile. This parameterdoesnot imposeany restrictionontheCPUtimeavailablefor thesimulationof asingleshower(or a groupof them),which is alwaysinfinite. time is any valid time specification.SeealsodirectivesRunsPerProcessandShowersPerRun.

MesonCutEnergySyntax: MesonCutEnergy energyDefault: MesonCutEnergy 60 MeV

(s) Minimum kinetic energy for mesons(pions,kaons,etc.). Every mesonhaving a kineticenergy below this thresholdis not taken into accountin thesimulation;unstableparticlesareforcedto decays.energymustbegreaterthanor equalto 500keV.


MFPHadr onicSyntax: MFPHadronic mfpselDefault: MFPHadronic SIBYLL (MFPHadronic QGSJET) for programAir es

(Air esQ).

(s) Directive to selectamongdifferentsetsof meanfreepathsparameterizations.mfpsel is acharacterstringthatcantake any oneof thefollowing values:Standard, SIBYLL QGSJET,or Bartol. Eachalternative correspondto differentparameterizationsfor themeanfreepathof hadron-airandnucleus-aircollisions.


MFPThr esholdSyntax: MFPThreshold energyDefault: MFPThreshold 50 GeV

(s,h) Thresholdenergy for the currently effective meanfree paths. All hadroniccollisionswith energy greaterthan or equalto this thresholdwill be processedusing the currentmfpparameterization(that canbe setusingdirective MFPHadr onic); otherwisestandardMFP’swill beused.energymustbegreaterthanor equalto 200MeV.


MinExtCollEner gySyntax: MinExtCollEnergy energyDefault: MinExtCollEnergy 200 GeV for theSIBYLL model;

MinExtCollEnergy 80 GeV for theQGSJETmodel.

(s,h)Thresholdenergy for invoking theexternalhadroniccollision routine(if enabled).energymustbegreaterthanor equalto 25 GeV.


MinExtNucCollEner gySyntax: MinExtNucCollEnergy energypernucleonDefault: MinExtCollEnergy 200 GeV for theSIBYLL model;

MinExtCollEnergy 80 GeV for theQGSJETmodel.

(s,h)Thresholdenergy pernucleonfor invoking theexternalnucleus-nucleuscollision routine(if enabled).energypernucleonmustbegreaterthanor equalto 25 GeV.

This directive hasno effect on simulationsperformedusing the old versionsof SIBYLL orQGSJET(programsAir esS16or Air esQ99, respectively), wherethenucleus-nucleuscollisions


pathsarealwaysevaluatedby meansof thebuilt-in AIRESnuclearfragmentationmodel.


MuonBremsstrahlungSyntax: Muonbremsstrahlung [ ) On * Off + ]Default: Muonbremsstrahlung is equivalentto Muonbremsstrahlung On

Muonbremsstrahlung On is assumedin caseof missingspecification.

(s,h) Switch to include/exclude the muon bremsstrahlung[18] and muonic pair productionprocessesfrom the muonpropagatingalgorithms.Theseinteractionsareenabledby default.Disablingthemmayleadto nonrealisticair shower simulations.


MuonCutEnergySyntax: MuonCutEnergy energyDefault: MuonCutEnergy 10 MeV

(s)Minimum kineticenergy for muons.Everymuonhaving akineticenergy below this thresh-old is not taken into accountin thesimulation;it is forcedto a decay. energymustbegreaterthanor equalto 500keV.

NuclCollisionsSyntax: NuclCollisions [ ) On * Off + ]Default: NuclCollisions is equivalentto NuclCollisions On

NuclCollisions On is assumedin caseof missingspecification.

(s,h)Switchto include/excludethehadronicinelasticcollisionswith air nucleusfrom theheavyparticlespropagatingalgorithms.Thecollisionsareenabledby default. Disablingthemmayleadto nonrealisticair shower simulations.


NuclCutEnergySyntax: NuclCutEnergy energyDefault: NuclCutEnergy 120 MeV

(s) Minimum kinetic energy for nucleonsand nuclei. Every suchparticle having a kineticenergy below this thresholdis not takeninto accountin thesimulation.energymustbegreaterthanor equalto 500keV.


ObservingLevelsSyntax: ObservingLevels nofol [ altdepth1 altdepth2]Default: ObservingLevels 19

(s) This directive definesthenumberandpositionof theobservinglevelsusedfor longitudinaldevelopmentrecording(seepage26) . altdepth1andaltdepth2arealtitude(or atmosphericdepth)specificationsthatdefinethepositionsof thefirst andlastobservinglevels. nofol is anintegerthatsetsthenumberof observinglevels. It mustlie in therangeT [\V]74U^2_Y . Theobservinglevels areequallyspacedin atmosphericdepthunits. The first (last) level correspondsto thehighest(lowest)altitude.

If altdepth1andaltdepth2arenot specified,thentheobservinglevelsareplacedbetweentheinjection and groundplanes,but spacingthem differently (seesection3.3.3): The injectionlevel correspondsto observinglevel “0” while thegroundlevel correspondsto observinglevel“nofol `aU ”. For example, if the injection (ground) level is placedat 0 (1000) g/cm0 , thedirective ObservingLevels 19 will set19 observinglevelsplacedat depths50, 100,150,. . . ,950g/cm0 .

OutputListingSyntax: OutputListing [ ) Brief * Full + ]Default: OutputListing is equivalentto OutputListing Brief

OutputListing Brief is assumedin caseof missingspecification.

(d) Hiddenoutputdataitemsarenot printedin theoutputsummaryfile unlessOutputListingFull is specified.

PerShowerDataSyntax: PerShowerData optionDefault: PerShowerData is equivalentto PerShowerData Full

PerShowerData Brief is assumedin caseof missingspecification.

(s) Directive to control theamountof individual shower datato bestoredaftereachshower iscompleted.option is a characterstring that cantake any oneof the following values:None,Brief or Full. WhenNone is specified,no individual shower datais saved.TheBrief levelimplies saving globalparameterssuchasthe depthof shower maximum bc?�Aed , for example;andtheFull level is theBrief level plusall thesingleshower tables(seepage119).

PhotoNuclearSyntax: PhotoNuclear [ ) On * Off + ]Default: PhotoNuclear is equivalentto PhotoNuclear On

PhotoNuclear On is assumedin caseof missingspecification.

(s,h) Switch to include/exclude the inelasticcollisionsgamma-airnucleus(photonuclearre-


actions)from the gammaray propagatingalgorithms.The collisionsareenabledby default.Disablingthemmayleadto nonrealisticair shower simulations.


PrimaryAzimAngleSyntax: PrimaryAzimAngle minang [ maxang] [ ) Magnetic * Geographic + ]Default: PrimaryAzimAngle 0 deg Magnetic if thezenithangleis fixed;

PrimaryAzimAngle 0 deg 360 deg Magnetic otherwise(seePrimaryZenAngle).

(s) Primary azimuthangle. The anglefor eachshower is selectedwith uniform probabilitydistribution in theinterval TminangV maxangY . If theanglemaxangis not specified,it is takenequalto minang (fixedazimuthangle).TheGeographickeyword indicatesthat thespecifiedazimuthis measuredwith respectto thegeographicnorth,positive for eastwardsdirections;inthis casetheazimuthangleusedby AIRES is obtainedapplyingequation(3.8). If no keywordor theMagnetic keyword is specified,thentheorigin for theazimuthsis themagneticnorth,andthegivenanglesareinterpretedaccordinglywith theorientationof theAIRES coordinatesystemdefinedin section2.1.1(page11).

PrimaryEner gySyntax: PrimaryEnergy minener[ maxener [ gamma] ]Default: None.This directive is alwaysrequired.

(s)Energy of primary. If only minener is specifiedthenall primarieshaveafixedenergy equalto this parameter. Otherwisethe energy will be sampledfrom the interval T 8;?f=@gJVh8;?�AediYcjTminenerV maxenerY with theprobabilitydistribution of equation(3.2)with exponentk option-ally specifiedby gamma.

Theprimaryenergy mustbelargerthan 7�2�2 MeV andlessthan U^2 Oml GeV( U^2 0on eV). Thereareno restrictionson k . If not specifiedit is setto 1.7.

PrimaryParticleSyntax: PrimaryParticle particle [ weight ]Default: None.This directive is alwaysrequired.

(s) Primaryparticlespecification.particle is theparticlename.Proton, Ir on, Feˆ56, etc. arevalid particlenames.Specialparticlenamesdefinedby meansof directiveAddSpecialParticlecan also be usedwith this instruction. If more than one PrimaryParticle directive appearwithin the input instructions,thentheprimaryparticleswill beselectedat randomamongthedifferentspecifiedparticlekinds,with probabilitiesproportionalto theweightsspecifiedin thecorrespondingweight fields. If weight is not specified,thentheparticleweightis takenas1.


PrimaryZenAngleSyntax: PrimaryZenAngle minang [ maxang[ ) S * SC * CS + ] ]Default: PrimaryZenAngle 0 deg

(s)Primaryzenithangle,p . If only minang is specified,thenthezenithangleis fixedandequalto thisvalue,andthedefault for theazimuthanglewill be0. Otherwisethezenithanglefor eachshower is selectedrandomlywithin the interval TminangV maxangY , with the sineprobabilitydistribution of equation(3.4),which is proportionalto qhrSRsp (default or S specification),or thesine-cosineprobabilitydistribution of equation(3.6),which is proportionalto qhrSR;put�M�q�p (SCor CS specifications).In this casethedefault for theazimuthangleis PrimaryAzimAngle 0deg360deg. Bothminang andmaxangmustbelongto theinterval T 2�v_V]W�2�v_w .

PrintTablesSyntax: PrintTables mincode[ maxcode] [ Options optstring]

PrintTables Clear

Default: No tablesareprintedby default.

(d) Tableswhosecodesrangefrom mincodeto maxcodeareselectedfor beingdisplayedin thesummaryoutputfile. If maxcodeis not specified,it is takenequalto mincode. Thetablecodesareintegers.A completelist of availabletables(morethan180)is placedin appendixC (page137),or canbeobtainedwith directivesHelp tablesand/orTableIndex. TheClear optionper-mits clearingthe list of printedtables,thusoverridingall thepreviousPrintTablesdirectives.opstring is astringof charactersto setavailableoptions:n suppressplottingminimum(<) andmaximum(>) characters;m includeminimumandmaximumplotsin thetables;M do not in-sertcharacterplots,make a completelynumericaltableinstead;S (R) usestandarddeviations(RMS errorsof themeans)to plot errorbars;r (d) normal(density)lateraldistributions;L (l)distributionsnormalizedas IJ-�ILK�M�NxO�P ( IJ-�ILKSR ). Thedefault optionsare:nSr.

PromptSyntax: Prompt [ ) On * Off + ]Default: Prompt is equivalentto Prompt On

Prompt Off is assumedin caseof missingspecification.

(d) Turnspromptingon/off. Thisdirective is meaningfulonly in interactive sessions.

PropagatePrimarySyntax: PropagatePrimary [ ) On * Off + ]Default: PropagatePrimary is equivalentto PropagatePrimary On

PropagatePrimary On is assumedin caseof missingspecification.

(s,h)This directive controlstheinitial propagationof theprimary. If theOn optionis selected(thedefault), thentheprimaryis normallyadvancedbeforethefirst interactiontakesplace,and


thereforethe first interactionaltitudewill be variable. Otherwisethe first interactionwill beforcedto occurat theinjectionaltitude.

This directive is ignoredfor showersinitiatedby specialprimaries(seesection3.5).

RandomSeedSyntax: RandomSeed seed

RandomSeed GetFrom idfileDefault: RandomSeed 0.0

(s) This directive setsthe randomnumbergeneratorseed. seedis a real number. If it be-longsto the interval yz24ViU_w thenthe seedis effectively taken asthe given number. Otherwiseit is evaluatedinternally (using the systemclock). The alternative syntaxwith the keywordGetFrom allows extractingtherandomgeneratorseedfrom analreadyexisting internaldumpfile.3 This is mostusefulto reproducinga previous simulationrepeatingthe original randomnumbersimulatorconfiguration.

RecordObsLevelsSyntax: RecordObsLevels [ Not ] [ lev1[ lev2 [ step] ] ]

RecordObsLevels [ Not ] ) All * All/step * None +Default: RecordObsLevels All

(s)Directive to markacertainsubsetof thedefinedobservinglevelsfor inclusion(or exclusion)in thesetof levels thatareincludedin the longitudinaltrackingcompressedparticlefile. Theintegervariableslev1 lev2andsteparetheargumentsof a FORTRAN do loop which startsatlev1, endsat lev2advancingin stepsof step. ThekeywordNot indicatesthatthecorrespondinglevelsmustbeexcludedfor beingrecordedin thefile. If lev2and/orsteparenot indicatedtheydefault to lev1and1 respectively. RecordObsLevelsAll /stepis a shortform for RecordOb-sLevels1 {}| step, where{~| is thenumberof definedobservinglevels.RecordObsLevelsAllis equivalentto RecordObsLevelsAll/1 while RecordObsLevels Nonecanbe usedin placeof RecordObsLevelsNot All . Thisdirectivecanberepeatedlyusedwithin aninput instructionstreamto markor unmarkarbitrarysubsetsof observinglevels,asexplainedin page93.

RemarkSyntax: Remark string

Remark &labelFirst line of remarks.. . .Lastline of remarks.&label

(s)Remarksdirective. Eachtimethisdirectiveappearsin theinputdatastream,thecorrespond-

3This is not supportedfor IDF filesgenerateswith AIRES versionspreviousto version2.0.0.


ing remarkstring(s)areappendedto theremarkstext. All theenteredremarkswill beprintedin the log andsummaryfiles, andstoredin differentoutputdatafiles. Thereis no limit in thenumberof remarklines,but every line cannotbelongerthan75 characters.

ResamplingRatioSyntax: ResamplingRatio rsratioDefault: ResamplingRatio 10

(s) This directive setsthevariable �� usedin theresamplingalgorithmdefinedin section4.2.1(page90). rsratio is a realnumberthatmustbegreateror equalthan1.

RLimsFileSyntax: RLimsFile filext rmin rmaxDefault: RLimsFile any file 250 m 12 km

(s) This directive definesthe lateral limits for the compresseddatafile whoseextension4 isfilext. For the groundparticlefile, rmin andrmax define,togetherwith the resamplingratiothat is controlledby theIDL instructionResamplingRatiotheradial limits of thezonewheretheparticlesaregoing to besaved (seepage90). In thecaseof longitudinaltrackingparticlefiles, thoseparametersdefinethe inclusionzoneat groundlevel. At an arbitraryaltitude,theparticlesareincludedaccordinglywith therulesexplainedin section4.2.1(page84).

RLimsTablesSyntax: RLimsTables rmin rmaxDefault: RLimsTables 50 m 2 km

(s)Thisdirective definestheradialinterval to usein thelateraldistribution tables(histograms).Eachlateraldistribution histogramconsistsof 40 logarithmicbins startingwith rmin (lowerradiusof bin 1) andendingwith rmax (upperradiusof bin 40).

RunsPerProcessSyntax: RunsPerProcess ) number * Infinite +Default: RunsPerProcess Infinite

(d) Numberof runswithin aprocess(seealsoMaxCpuTimePerRun andShowersPerRun).

SaveInFileSyntax: SaveInFile filext particle1[ particle2] . . .Default: SaveInFile grdpcles All

SaveInFile lgtpcles None

(s)Thisdirectiveallowsto controltheparticlesbeingsavedin thecompressedfile whoseexten-sion is filext (seedirective RLimsFile). particle1, particle2, . . . , arevalid particleor particle

4Theextensionof afile is whatgoesafterthedot in thefile name,like in fname.extensionfor instance.


groupnames.This directive, togetherwith SaveNotInFile areusefulto save outputfile spacein certaincircumstances.

SaveNotInFileSyntax: SaveNotInFile filext particle1[ particle2] . . .

(s)Thesyntaxof thisdirective is similarto SaveInFile, andits meaningis opposite(SaveInFilefilext None is equivalentto SaveNotInFile filext All ).

SeparateShowersSyntax: SeparateShowers ) Off * number +Default: SeparateShowers Off

(s) In a task involving more than one shower, the compressedoutput files can be split intoseveralpieceseachonestoringthedatacorrespondingto numbershowers.In particular, Sepa-rateShowers1 generatesonecompressedfile pershowerwhile SeparateShowersOff disablesfile splitting.

SetGlobalSyntax: SetGlobal [ ) Dynamic * Static + ] varnamevalueDefault: No environmentalvariablesareimportedby default.

(d) Settingglobalvariables.Thevariablevarnameis setto thestringvalue. If thevariablewasalreadyset,thenits old settingis superseded.ThedefinedvariablescaneitherbeusedwithintheIDL input streamor passedto thecompressedoutputfilesor specialprimarymodules.TheDynamic qualifier(default) indicatesthedynamiccharacterof thecorrespondingvariable.Thismeansthat thevaluecurrentlypassedto theexternalmodulesis modifiedeachtime AIRES isinvoked for a given task. On theotherhand,Static variablesaresetat thefirst invocationofAIRES; andfurthersettingshave noeffect.

SetTimeAtInjectionSyntax: SetTimeAtInjection [ ) On * Off + ]Default: SetTimeAtInjection is equivalentto SetTimeAtInjection On

SetTimeAtInjection On is assumedin caseof missingspecification.

(s,h)Directive to setwhetherthetimecountfor eachshower is startedat themomentof inject-ing theprimaryparticle(On) or at its first interaction(Off ).

This directive is ignoredfor showersinitiatedby specialprimaries(seesection3.5).

ShowersPerRunSyntax: ShowersPerRun ) number * Infinite +Default: ShowersPerRun Infinite

(d) Maximumnumberof showersin a run (seealsoMaxCpuTimePerRun andRunsPerPro-


cess). Notice that this parameteris relatedwith thecomputerenvironmentonly anddoesnotaffect thetotal numberof showersthatdefinea task(seeTotalShowers).

SiteSyntax: Site nameDefault: Site Site00

(s) The Site directive specifythe geographicallocationthat definethe environment(latitude,longitudeandaltitude)wherethesimulationstake place. name is a string identifying these-lectedsite. It musteitherbeoneof thepredefinedsitesof theAIRESsitelibrary, listedin table3.2(page64),or have beenpreviously definedby meansof theAddSite directive.

SkipSyntax: Skip &label

(d) Instructiontoskippartof aninputdatastream.All directivesplacedaftertheSkip statementandbefore& label areskipped.Noticethatthis is nota “go to” statement:It is only possibletoskip forwards,never backwards.

SpecialParticLogSyntax: SpecialParticLog lvlDefault: SpecialParticLog is equivalentto SpecialParticLog 1

SpecialParticLog 0 is assumedin caseof missingspecification.

(d) Controlling the amountof datarelatedwith specialprimary particlesto be saved in thecorrespondinglog file. lvl is anintegerparameterthatcantake thefollowing values:

0 No informationwritten in thelog file.1 Messagesbeforeandafterinvoking theexternalmodule.2 Level 1 plusdetailedlist of valid primaries.

StackInformationSyntax: StackInformation [ ) On * Off + ]Default: StackInformation is equivalentto StackInformation On

StackInformation Off is assumedin caseof missingspecification.

(d) Directive to instructAIRESto print detailedstackusageinformationin thesummaryoutputfile.

SummarySyntax: Summary [ ) On * Off + ]Default: Summary is equivalentto Summary On

Summary On is assumedin caseof missingspecification.

(d) Directive to enableor disabletheoutputsummary.


TableIndexSyntax: TableIndex [ ) On * Off + ]Default: TableIndex is equivalentto TableIndex On

TableIndex Off is assumedin caseof missingspecification.

(d) Directive to instructAIRES to print a tableindex in thesummaryoutputfile.

TaskNameSyntax: TaskName [ Append ] taskname[ taskversion ]Default: TaskName GIVE ME A NAME PLEASE

(d) Tasknameassignment.tasknameis a characterstringwhich identifiesthecurrenttask. Ifits lengthis greaterthan64characters,it will betruncatedto thefirst 64characters.taskversionis anoptionalintegerbetween0 (default) and999. If taskversion is not zero,theeffective tasknameis tasknametaskversion. If thekeyword Append is used,thentasknameis appendedtotheexisting tasknamestring.Thetasknameis usedto setthefile namesof all outputfiles.

ThinningEnergySyntax: ThinningEnergy ) energy * number Relative +Default: ThinningEnergy 1.0e-4 Relative

(s) Thinning energy. It canbe expressedeitherasan absoluteenergy or asa real (positive)numberwith the keyword Relative (In this casethe thinning energy is the primary energytimesthespecifiednumber).

ThinningWF actorSyntax: ThinningWFactor numberDefault: ThinningWFactor 12

(s,h)Thinningweightfactor.This instructionpermitssettingtheweightfactor �� of equation(2.23).

TotalShowersSyntax: TotalShowers nofshowersDefault: None.This directive is alwaysrequired.

(d) Total numberof showers. nofshowers is a positive integer in the range T�U�V'5�7�W�X�5�7ZY defin-ing the numberof showersto be simulatedin the currenttask. Notice that this is a dynamicparameter, thatis, it canbemodified(eitherenlargedor reduced)duringthesimulations.


TraceSyntax: Trace [ ) On * Off + ]Default: Trace is equivalentto Trace On

Trace Off is assumedin caseof missingspecification.

(d) Directive to enableor disableinput datatracing. If enabled(On) thentraceinformationaboutthedirectivesbeingprocessedby theIDL parseris written into thestandardoutputchan-nel. Thisdirective is usefulto debug IDL inputdatasets.

TSSFileSyntax: TSSFile [ ) On * Off + ]Default: TSSFile is equivalentto TSSFile On

TSSFile Off is assumedin caseof missingspecification.

(d) If TSSFile On is specified,thena tasksummaryscript file will be generatedupon taskcompletion.Thetasksummaryscriptfile (TSS)is aplain text file containinginformationaboutthemainparametersof thesimulation,in theformatKeyword = value, suitablefor processingwith otherprograms.

Appendix C

Output data table inde x

We list hereall the tablesdefinedin AIRES 2.6.0. Thesetablescanbe processedusingdirectivesPrintTablesand/orExportTables(seechapter3).

Code Tablename

1 1001 Longitudinaldevelopment:Gammarays.2 1005 Longitudinaldevelopment:Electrons.3 1006 Longitudinaldevelopment:Positrons.4 1007 Longitudinaldevelopment:Muons( ` ).5 1008 Longitudinaldevelopment:Muons( � ).6 1011 Longitudinaldevelopment:Pions( ` ).7 1012 Longitudinaldevelopment:Pions( � ).8 1013 Longitudinaldevelopment:Kaons( ` ).9 1014 Longitudinaldevelopment:Kaons( � ).

10 1021 Longitudinaldevelopment:Neutrons.11 1022 Longitudinaldevelopment:Protons.12 1023 Longitudinaldevelopment:Antiprotons.13 1041 Longitudinaldevelopment:Nuclei.14 1091 Longitudinaldevelopment:Otherchargedpcles.15 1092 Longitudinaldevelopment:Otherneutralpcles.16 1205 Longitudinaldevelopment:e ande�17 1207 Longitudinaldevelopment:mu andmu�18 1211 Longitudinaldevelopment:pi ` andpi �19 1213 Longitudinaldevelopment:K ` andK �20 1291 Longitudinaldevelopment:All chargedparticles.21 1292 Longitudinaldevelopment:All neutralparticles.22 1293 Longitudinaldevelopment:All particles.

23 1301 Unweightedlongit. development:Gammarays.24 1305 Unweightedlongit. development:Electrons.25 1306 Unweightedlongit. development:Positrons.

137

138 APPENDIX C. OUTPUT DATA TABLE INDEX

Code Tablename

26 1307 Unweightedlongit. development:Muons( ` ).27 1308 Unweightedlongit. development:Muons( � ).28 1311 Unweightedlongit. development:Pions( ` ).29 1312 Unweightedlongit. development:Pions( � ).30 1313 Unweightedlongit. development:Kaons( ` ).31 1314 Unweightedlongit. development:Kaons( � ).32 1321 Unweightedlongit. development:Neutrons.33 1322 Unweightedlongit. development:Protons.34 1323 Unweightedlongit. development:Antiprotons.35 1341 Unweightedlongit. development:Nuclei.36 1391 Unweightedlongit. development:Otherchargedpcles.37 1392 Unweightedlongit. development:Otherneutralpcles.38 1405 Unweightedlongit. development:e ande�39 1407 Unweightedlongit. development:mu andmu�40 1411 Unweightedlongit. development:pi ` andpi �41 1413 Unweightedlongit. development:K ` andK �42 1491 Unweightedlongit. development:All chargedparticles.43 1492 Unweightedlongit. development:All neutralparticles.44 1493 Unweightedlongit. development:All particles.

45 1501 Longitudinaldevelopment:Energy of gammarays.46 1505 Longitudinaldevelopment:Energy of electrons.47 1506 Longitudinaldevelopment:Energy of positrons.48 1507 Longitudinaldevelopment:Energy of muons( ` ).49 1508 Longitudinaldevelopment:Energy of muons( � ).50 1511 Longitudinaldevelopment:Energy of pions( ` ).51 1512 Longitudinaldevelopment:Energy of pions( � ).52 1513 Longitudinaldevelopment:Energy of kaons( ` ).53 1514 Longitudinaldevelopment:Energy of kaons( � ).54 1521 Longitudinaldevelopment:Energy of neutrons.55 1522 Longitudinaldevelopment:Energy of protons.56 1523 Longitudinaldevelopment:Energy of antiprotons.57 1541 Longitudinaldevelopment:Energy of nuclei.58 1591 Longitudinaldevelopment:Energy of otherchargedparticles.59 1592 Longitudinaldevelopment:Energy of otherneutralparticles.60 1705 Longitudinaldevelopment:Energy of e ande�61 1707 Longitudinaldevelopment:Energy of mu andmu�62 1711 Longitudinaldevelopment:Energy of pi ` andpi �63 1713 Longitudinaldevelopment:Energy of K ` andK �64 1791 Longitudinaldevelopment:Energy of all chargedparticles.65 1792 Longitudinaldevelopment:Energy of all neutralparticles.66 1793 Longitudinaldevelopment:Energy of all particles.

APPENDIX C. OUTPUT DATA TABLE INDEX 139

Code Tablename

67 2001 Lateraldistribution: Gammarays.68 2005 Lateraldistribution: Electrons.69 2006 Lateraldistribution: Positrons.70 2007 Lateraldistribution: Muons( ` ).71 2008 Lateraldistribution: Muons( � ).72 2011 Lateraldistribution: Pions( ` ).73 2012 Lateraldistribution: Pions( � ).74 2013 Lateraldistribution: Kaons( ` ).75 2014 Lateraldistribution: Kaons( � ).76 2021 Lateraldistribution: Neutrons.77 2022 Lateraldistribution: Protons.78 2023 Lateraldistribution: Antiprotons.79 2041 Lateraldistribution: Nuclei.80 2091 Lateraldistribution: Otherchargedpcles.81 2092 Lateraldistribution: Otherneutralpcles.82 2205 Lateraldistribution: e ande�83 2207 Lateraldistribution: mu andmu�84 2211 Lateraldistribution: pi ` andpi �85 2213 Lateraldistribution: K ` andK �86 2291 Lateraldistribution: All chargedparticles.87 2292 Lateraldistribution: All neutralparticles.88 2293 Lateraldistribution: All particles.

89 2301 Unweightedlateraldistribution: Gammarays.90 2305 Unweightedlateraldistribution: Electrons.91 2306 Unweightedlateraldistribution: Positrons.92 2307 Unweightedlateraldistribution: Muons( ` ).93 2308 Unweightedlateraldistribution: Muons( � ).94 2311 Unweightedlateraldistribution: Pions( ` ).95 2312 Unweightedlateraldistribution: Pions( � ).96 2313 Unweightedlateraldistribution: Kaons( ` ).97 2314 Unweightedlateraldistribution: Kaons( � ).98 2321 Unweightedlateraldistribution: Neutrons.99 2322 Unweightedlateraldistribution: Protons.

100 2323 Unweightedlateraldistribution: Antiprotons.101 2341 Unweightedlateraldistribution: Nuclei.102 2391 Unweightedlateraldistribution: Otherchargedpcles.103 2392 Unweightedlateraldistribution: Otherneutralpcles.104 2405 Unweightedlateraldistribution: e ande�105 2407 Unweightedlateraldistribution: mu andmu�106 2411 Unweightedlateraldistribution: pi ` andpi �107 2413 Unweightedlateraldistribution: K ` andK �


Code Tablename

108 2491 Unweightedlateraldistribution: All chargedparticles.109 2492 Unweightedlateraldistribution: All neutralparticles.110 2493 Unweightedlateraldistribution: All particles.

111 2501 Energy distribution atground:Gammarays.112 2505 Energy distribution atground:Electrons.113 2506 Energy distribution atground:Positrons.114 2507 Energy distribution atground:Muons( ` ).115 2508 Energy distribution atground:Muons( � ).116 2511 Energy distribution atground:Pions( ` ).117 2512 Energy distribution atground:Pions( � ).118 2513 Energy distribution atground:Kaons( ` ).119 2514 Energy distribution atground:Kaons( � ).120 2521 Energy distribution atground:Neutrons.121 2522 Energy distribution atground:Protons.122 2523 Energy distribution atground:Antiprotons.123 2541 Energy distribution atground:Nuclei.124 2591 Energy distribution atground:Otherchargedpcles.125 2592 Energy distribution atground:Otherneutralpcles.126 2705 Energy distribution atground:e ande�127 2707 Energy distribution atground:mu andmu�128 2711 Energy distribution atground:pi ` andpi �129 2713 Energy distribution atground:K ` andK �130 2791 Energy distribution atground:All chargedparticles.131 2792 Energy distribution atground:All neutralparticles.132 2793 Energy distribution atground:All particles.

133 2801 Unweightedenergy distribution: Gammarays.134 2805 Unweightedenergy distribution: Electrons.135 2806 Unweightedenergy distribution: Positrons.136 2807 Unweightedenergy distribution: Muons( ` ).137 2808 Unweightedenergy distribution: Muons( � ).138 2811 Unweightedenergy distribution: Pions( ` ).139 2812 Unweightedenergy distribution: Pions( � ).140 2813 Unweightedenergy distribution: Kaons( ` ).141 2814 Unweightedenergy distribution: Kaons( � ).142 2821 Unweightedenergy distribution: Neutrons.143 2822 Unweightedenergy distribution: Protons.144 2823 Unweightedenergy distribution: Antiprotons.145 2841 Unweightedenergy distribution: Nuclei.146 2891 Unweightedenergy distribution: Otherchargedpcles.147 2892 Unweightedenergy distribution: Otherneutralpcles.


Code Tablename

148 2905 Unweightedenergy distribution: e ande�149 2907 Unweightedenergy distribution: mu andmu�150 2911 Unweightedenergy distribution: pi ` andpi �151 2913 Unweightedenergy distribution: K ` andK �152 2991 Unweightedenergy distribution: All chargedparticles.153 2992 Unweightedenergy distribution: All neutralparticles.154 2993 Unweightedenergy distribution: All particles.

155 3001 Meanarrival time distribution: Gammarays.156 3005 Meanarrival time distribution: Electronsandpositrons.157 3007 Meanarrival time distribution: Muons.158 3091 Meanarrival time distribution: Otherchargedpcles.159 3092 Meanarrival time distribution: Otherneutralpcles.160 3291 Meanarrival time distribution: All chargedparticles.161 3292 Meanarrival time distribution: All neutralparticles.162 3293 Meanarrival time distribution: All particles.

163 5001 Numberandenergy of groundgammasversusshower number.164 5005 Numberandenergy of grounde� versusshower number.165 5006 Numberandenergy of grounde versusshower number.166 5007 Numberandenergy of groundmu versusshower number.167 5008 Numberandenergy of groundmu� versusshower number.168 5011 Numberandenergy of groundpi ` versusshower number.169 5012 Numberandenergy of groundpi � versusshower number.170 5013 Numberandenergy of groundK ` versusshower number.171 5014 Numberandenergy of groundK � versusshower number.172 5021 Numberandenergy of groundneutronsversusshower number.173 5022 Numberandenergy of groundprotonsversusshower number.174 5023 Numberandenergy of groundpbarversusshower number.175 5041 Numberandenergy of groundnucleiversusshower number.176 5091 Numberandenergy of othergrd.ch.pcles.versusshower number.177 5092 Numberandenergy of othergrd.nt. pcles.versusshower number.178 5205 Numberandenergy of grounde ande� versusshower number.179 5207 Numberandenergy of groundmu andmu� versusshower number.180 5211 Numberandenergy of groundpi ` andpi � versusshower number.181 5213 Numberandenergy of groundK ` andK � versusshower number.182 5291 Numberandenergy of groundch.pcles.versusshower number.183 5292 Numberandenergy of groundnt. pcles.versusshower number.184 5293 Numberandenergy of all groundparticlesversusshower number.185 5501 XmaxandNmax(chargedparticles)versusshower number.186 5511 First interact.depthandprimaryenergy versusshower number.187 5513 Zenithandazimuthanglesversusshower number.


Code Tablename

188 7001 Longitudinaldevelopment:Low energy gammarays.189 7005 Longitudinaldevelopment:Low energy electrons.190 7006 Longitudinaldevelopment:Low energy positrons.191 7007 Longitudinaldevelopment:Low energy muons(+).192 7008 Longitudinaldevelopment:Low energy muons(-).193 7091 Longitudinaldevelopment:Otherchargedlow egy. pcles.194 7092 Longitudinaldevelopment:Otherneutrallow egy. pcles.195 7205 Longitudinaldevelopment:Low energy e+ande-196 7207 Longitudinaldevelopment:Low energy mu+andmu-197 7291 Longitudinaldevelopment:All low energy chargedpcles.198 7292 Longitudinaldevelopment:All low energy neutralpcles.199 7293 Longitudinaldevelopment:All low energy pcles.

200 7301 Unweightedlongit. devel.: Low energy gammarays.201 7305 Unweightedlongit. devel.: Low energy electrons.202 7306 Unweightedlongit. devel.: Low energy positrons.203 7307 Unweightedlongit. devel.: Low energy muons(+).204 7308 Unweightedlongit. devel.: Low energy muons(-).205 7391 Unweightedlongit. devel.: Otherchargedlow egy. pcles.206 7392 Unweightedlongit. devel.: Otherneutrallow egy. pcles.207 7405 Unweightedlongit. devel.: Low energy e+ande-208 7407 Unweightedlongit. devel.: Low energy mu+andmu-209 7491 Unweightedlongit. devel.: All low energy chargedpcles.210 7492 Unweightedlongit. devel.: All low energy neutralpcles.211 7493 Unweightedlongit. devel.: All low energy pcles.

212 7501 Longitudinaldevelopment:Energy of low egy. gammarays.213 7505 Longitudinaldevelopment:Energy of low egy. electrons.214 7506 Longitudinaldevelopment:Energy of low egy. positrons.215 7507 Longitudinaldevelopment:Energy of low egy. muons(+).216 7508 Longitudinaldevelopment:Energy of low egy. muons(-).217 7591 Longitudinaldevelopment:Egy. of otherchargedlow egy. pcles.218 7592 Longitudinaldevelopment:Egy. of otherneutrallow egy. pcles.219 7705 Longitudinaldevelopment:Energy of low egy. e+ande-220 7707 Longitudinaldevelopment:Energy of low egy. mu+andmu-221 7791 Longitudinaldevelopment:Egy. of all low egy. chargedpcles.222 7792 Longitudinaldevelopment:Egy. of all low egy. neutralpcles.223 7793 Longitudinaldevelopment:Egy. of all low energy pcles.

224 7801 Longitudinaldevelopment:Energy depositedby gammarays.225 7805 Longitudinaldevelopment:Energy depositedby electrons.226 7806 Longitudinaldevelopment:Energy depositedby positrons.227 7807 Longitudinaldevelopment:Energy depositedby muons(+).


Code Tablename

228 7808 Longitudinaldevelopment:Energy depositedby muons(-).229 7891 Longitudinaldevelopment:Egy. depositedby otherchargedpcles.230 7892 Longitudinaldevelopment:Egy. depositedby otherneutralpcles.231 7905 Longitudinaldevelopment:Energy depositedby e+ande-232 7907 Longitudinaldevelopment:Energy depositedby mu+andmu-233 7991 Longitudinaldevelopment:Egy. depositedby all chargedpcles.234 7992 Longitudinaldevelopment:Egy. depositedby all neutralpcles.235 7993 Longitudinaldevelopment:Energy depositedby all pcles.

Appendix D

The AIRES object librar y

TheAIRESobjectlibrary is acollectionof modulesthatareusefulin severalapplications,including(but not limited to) specialprimarymodules(seesection3.5),andoutputfile processing,particularlycompressedfiles generatedby theAIRES compressedi/o unit (CIO). Most of the routineswerees-peciallywritten for thesepurposes,but someof themareof generalnatureandarealsousedby thesimulationand/orsummaryprograms.

D.1 C interface

Themodulesof theAIRES objectlibrary arecallablefrom aC program.In generalthecallingstate-mentis similar to theFORTRAN one,takinginto accountthatall argumentsarepassedby reference.Thatmeansthattheactualargumentsmustbepointersto thecorrespondingdataitems.

Thisrequirementis madeevidentwhendescribingthedifferentroutinesby placinganampersand(& ) beforethecorrespondingarguments.TheexperiencedC programmerwill understand,however,that this characteris not requiredin actualcalling statementscontainingpointervariablesasargu-ments.Thefollowing exampleillustratesthispoint:

int *channel, *vrb, *irc;int recnumber;int crogotorec();. . .if (crogotorec(channel, &recnumber, vrb, irc)) ) . . .

All theargumentsof crogotorec aredefinedaspointers,exceptrecnumberwhich is declaredasanintegervariable.The& placedbeforethisargumentensuresthatthis variablebepassedby referenceto thecalledroutine.

In general,all theFORTRAN routinesof thelibrary canbedirectly calledfrom a C program.Ina few casesit wasnecessaryto write specialC routines,which werenamedappendinga “c” to theoriginal FORTRAN name,asin thecaseof opencrofile that mustbe calledopencrofilec from a Cprogram(seepage196).

144

APPENDIX D. THE AIRES OBJECT LIBRARY 145

It is alsoworthwhilementioningthatsomeFORTRAN compilersdoplaceanunderscore( ) afterthenamesof theroutines.In suchcasesthis charactermustbemanuallyappendedto all theroutinesusedwithin theC program,excluding,of course,all thespecialC routinesof thepreviousparagraph.

D.2 List of most frequentl y used librar y modules.

In this appendixwe list thedefinitionsof themostfrequentlyusedroutines,alphabeticallyordered.At eachcasetheFORTRAN aswell astheC callingstatementsareplaced.

cioclose

FORTRAN call cioclose

C cioclose;

Closingall thecurrentlyalreadyopenedCIO files.

cioclose1

FORTRAN call cioclose1(channel)

C cioclose1(&channel);

ClosinganalreadyopenedCIO file.

Ar guments:

channel (Input, integer) Variable that uniquely identifiesthe I/O channelassignedto thecorrespondingfile. Thisvariablemustbealreadysetby meansof routineopencrofile.

146 APPENDIX D. THE AIRES OBJECT LIBRARY

ciorinit

FORTRAN call ciorinit(inilevel, codsys, vrb, irc)

C ciorinit(&inilevel, &codsys, &vrb, &irc);

Initializing theAIRES compressedI/O systemfor readingdata.This routinemustbeinvokedat thebeginningof every programusingthecompressedI/O systemroutines.

Ar guments:

inilevel (Input, integer) Initializationswitch. If inilevel is zeroor negative,all neededinitial-izationroutinesarecalled. If positive only theCIO systemis initialized (Theotherrou-tinesmustbecalledwithin the invoking program,beforecalling ciorinit: �z�9��>��4��j�Umeanscompletecio initialization,while �z�9��>��4��U impliesonly particlecodinginitial-ization. This lastcaseallows changingtheparticlecodingsystemat any momentduringaCIO processingsession.

codsys (Input, integer) Particlecodingsystemidentification.This variablepermitsselectingamongseveralparticlecodingsystemssupportedby AIRES (seetable4.7). Themenuofavailablesystemsis thefollowing:

0 AIRES internalcodingsystem.

1 AIRESinternalcodingfor elementaryparticlesanddecimalnuclearnotation( �(��IQ�Fj/�`�U^2�2��, ).

4 ParticleDataGroupcodingsystem[32] extendedwith decimalnuclearnotation.1

5 CORSIKA programparticlecodingsystem[30].

6 GEANT particlecodingsystem[33].

8 SIBYLL particlecodingsystem[6], extendedwith decimalnuclearnotation.

9 MOCCA styleparticlecodingsystem,extendedwith decimalnuclearnotation.

– Any othervalueis equivalentto ��^��j U .vrb (Input, integer) Verbositycontrol. If vrb is zeroor negative thenno erroror informative

messagesareprinted;error conditionsarecommunicatedto thecalling programvia thereturn code. If vrb is positive error messageswill be printed: �H¡_¢£j¤U meansthatmessageswill be printedeven with successfuloperations. �H¡_¢¥j§¦QV]X meansthat onlyerrormessageswill beprinted. �H¡_¢��¨X is similar to �H¡Z¢�jaX , but with theadditionalactionof stoppingtheprogramif a fatalerrortakesplace.

ir c (Output, integer) Returncode.0 meanssuccessfulreturn.1 meansthataninvalid particlecodingsystemwasspecifiedby codsys(in thiscasethedefault codingsystemis used).

1For nucleithenotation: ©eª]«i¬®°¯²±´³oµ(µ'µ(µ'µ9¶�· , is used.


ciorshutdown

FORTRAN call ciorshutdown

C ciorshutdown;

Terminating(in anorderedfashion)a compressedfile analysissession.This routineshouldbeinvokedat theendof every CIO processingprogram.


clockrandom

FORTRAN r = clockrandom()

C r = clockrandom();

This function invokestheAIRES elementaryrandomnumbergeneratorandreturnsa pseudo-randomnumberuniformly distributedin theinterval yz24ViU_w , generatedwith thecurrentclockandCPUusagelectures.No initialization is neededbeforeusingthis randomnumbergenerator.

WARNING: This function is not to be usedasa high quality random number generator.This routine is intendedonly for somespecialapplicationslike generatinga single randomseed,for example.

Multiple calls may eventually returncorrelatednumbersif thereis no enoughtime betweeninvocations.Nevertheless,a sequenceof differentnumberspassesdirect1d and2d chi-squaretests,ensuringaminimumquality for thegeneratednumbers.

Returnedvalue: (Doubleprecision) Theuniform pseudo-randomnumber.


crofieldindex

FORTRAN idx = crofieldindex(channel, rectype, fieldname,vrb, datype, irc)

C idx = crofieldindex(&channel, &rectype,&fieldname, &vrb, &datype,&irc);

Returningtheindex correspondingto agivenfield within acompressedfile record.It is conve-nient to usethis routineto setintegervariables,andusethemto managethedatareturnedbygetcrorecord, asexplainedin section4.2.2(page94).

Ar guments:


rectype (Input, integer) Recordtype(0 for default recordtype).

fieldname (Input, characterstring) Firstcharactersof field name(enoughcharactersmustbeprovidedto make anunambiguousspecification).

vrb (Input, integer) Verbositycontrol. If vrb is zeroor negative thenno erroror informativemessagesareprinted;error conditionsarecommunicatedto thecalling programvia thereturn code. If vrb is positive error messageswill be printed: �H¡_¢£j¤U meansthatmessageswill be printedeven with successfuloperations. �H¡_¢¥j§¦QV]X meansthat onlyerrormessageswill beprinted. �H¡_¢��¨X is similar to �H¡Z¢�jaX , but with theadditionalactionof stoppingtheprogramif a fatalerrortakesplace.

datype (Output, integer) Thedatatype that correspondsto thespecifiedfield: 1 for integerdata,2 for date-timedata,and3 for realdata.

ir c (Output, integer) Returncode.0 meanssuccessfulreturn.

Returnedvalue: (Integer) Thefield index. Zeroif therewasanerror.


crofileinfo

FORTRAN call crofileinfo(channel, ouflag, vrb, irc)

C crofileinfo(&channel, &ouflag, &vrb, &irc);

Printing information about the recordsof an alreadyopenedcompressedfile. This routineretrievesinformationaboutthecompleterecordstructureof thecorrespondingfile: How manyrecordtypesaredefined,andfor eachrecordtypethenumberof fieldsanda list of theirnamesandrelative logicalpositions.Theorderingin thelist of fieldsis equalto theorderingof dataintheintegerandrealarraysreturnedby routinegetcrorecord whenreadingarecordof thesametype.

Ar guments:


ouflag (Integer, input) Logicaloutputunit(s)selectionflag. Seeroutinecroheaderinfo.




crofileversion

FORTRAN ivers = crofileversion(channel)

C ivers = crofileversion(&channel);

ReturningtheAIRES versionusedto write analreadyopenedcompressedfile.

Ar guments:


Returnedvalue: (Integer) Thecorrespondingversionin integerformat(for examplethenum-ber01040200for version1.4.2,01040201for version1.4.2a,etc.).If thefile is notopenedor if thereis anerror, thenthereturnvalueis negative.


crogotorec

FORTRAN okflag = crogotorec(channel, recnumber, vrb,irc)

C okflag = crogotorec(&channel, &recnumber, &vrb,&irc);

Positioningthefile aftera givenrecord.This routine,usedin connectionwith crorecnumber,allows emulatingdirectaccessto compressedfiles. Noticehowever thata completelyrandomaccessregimewith very largefilesmayeventuallyimply longerprocessingtimes.

Ar guments:


recnumber (Input, integer) Therecordnumber. A negative valueis takenaszero.If ¡Z�J�J��¸�¹u¢f�4¡~º»2 , thereturncodeisalwayssettozerofor successfuloperations(Noticethatin thiscasethefile will bepositionedat thebeginningof thedatarecords).


ir c (Output, integer) Returncode.Themeaningsof thedifferentvaluesthatcanbereturnedare as explainedfor routine getcrorecord. When the return code is a recordtype, itcorrespondsto therecordtypeof the last scannedrecord.

Returnedvalue: (Logical) Trueif thepositioningwassuccessfullydone.Falseotherwise.


croheaderinfo

FORTRAN call croheaderinfo(ouflag, vrb, irc)

C croheaderinfo(&ouflag, &vrb, &irc);

Printing a summaryof the informationcontainedin the headerof the mostrecentlyopenedcompressedfile.

Ar guments:

ouflag (Input, integer) Logical outputunit(s)selectionflag: 0 or negative meansFORTRANunit 6only, 1meansunit 7only, 2meansbothunits6and7,3meansunit 8only, �x¸H¼®½¿¾��À

meansunit ouflag only. FORTRAN unit 6 correspondsto thestandardoutputchannel.




croinputdata0

FORTRAN call croinputdata0(intdata, realdata, shprimcode,shprimwt)

C croinputdata0(&intdata[1], &realdata[1],&shprimcode[1], &shprimwt[1]);

Copying into arrayssomeheaderdataitemscorrespondingto themostrecentlyopenedcom-pressedfile. Notice that someadditionalinput parametersmust be retrieved using routinesgetinpreal, getinpint or getinpswitch (seepages176–179).

Ar guments:

intdata (Output, integer, array(*)) Integer dataarray. The calling programmust provideenoughspacefor it. Thefollowing list describesthedifferentdataitems:

1 Numberof differentprimaryparticles.2-4 Reservedfor futureuse.

5 Primaryenergy distribution: 0 fixedenergy; 1 varyingenergy.6 Zenithangledistribution: 0, fixedangle;1, sinedistribution (equation(3.4)) ;

2, sine-cosinedistribution (equation(3.6)).7 Azimuth angledistribution: 0 (10), fixed angle(geographicazimuth);1 (11),

varyingangle(geographicazimuths).8 Numberof observinglevels.9 Atmosphericmodellabel(Seepage116).

10-14 Reservedfor futureuse.15 First shower number.

realdata (Output, double precision, array(*)) Real dataarray. The calling programmustprovide enoughspacefor it. Thefollowing list describesthedifferentdataitems:

1 Minimum primaryenergy (GeV).2 Maximumprimaryenergy (GeV).3 Exponentk of energy distribution (equation(3.2)).4 Minimum zenithangle(deg).5 Maximumzenithangle(deg).6 Minimum azimuthangle(deg).7 Maximumazimuthangle(deg).8 Thinningenergy parameter.2

2Thethinningenergy parameter, ÁDÂ , mustbeinterpretedasfollows: Whenpositive, it givestheabsolutethinningenergyin GeV. Otherwiseit indicatesa relative thinningspecification,being Ã�Ä�Åf�Æ ÁSÂ_Æ Ã�ÇBÈ�É Ê\Ë�ÈÍÌ .


9 Injectionaltitude(m).3

10 Injectiondepth(g- cm0 ).11 Groundaltitude(m).12 Grounddepth(g- cm0 ).

13-14 Reservedfor futureuse.15 Altitude of first observinglevel (m).16 Verticaldepthof first observinglevel (g- cm0 ).17 Altitude of lastobservinglevel (m).18 Verticaldepthof lastobservinglevel (g- cm0 ).19 Distancebetweenconsecutive observinglevelsin g- cm0 .20 Sitelatitude(deg).21 Sitelongitude(deg).22 Geomagneticfield strength,F, (nT).23 Local geomagneticinclination,I, (deg).24 Local geomagneticdeclination,D, (deg).25 Amplitudeof randomfluctuationof magneticfield4.

26-29 Reservedfor futureuse.30 Minimum lateraldistanceusedfor groundparticlehistograms(m).31 Maximumlateraldistanceusedfor groundparticlehistograms(m).32 Minimum energy usedfor histograms(GeV).33 Maximumenergy usedfor histograms(GeV).

34-35 Reservedfor futureuse.36 Minimum radial distanceparameterfor the mostrecentlyopenedcompressed

file (m).37 Maximumradial distanceparameterfor themostrecentlyopenedcompressed

file (m).

shprimcode (Output, integer, array(*)) For Î from 1 to �z��Ï�®½\Ï½�yBU_w , �Ð�Ñ®¡��z¹Ò��®��yzÎow givesthecorrespondingprimaryparticlecode.Thecodingsystemusedis theonedefinedwhenstartingthecio system.

shprimwt (Output, doubleprecision,array(*)) For Î from 1 to �z��Ï�®½\Ï½�yBU_w , �Ð®Ñ�¡��z¹ÔÓ²Ï�yzÎBwgivesthecorrespondingprimary particleweight. This weight is 1 in thesingleprimarycase.

3Measuredvertically, startingfrom the intersectionpoint betweenthesealevel andtheline thatgoesform theEarth’scenterto theparticleinjectionpoint, i.e., ÕhÖ in figure2.1.

4Themagneticfluctuationparameter, ×eÂ , mustbeinterpretedasfollows: Whenpositive, it givestheabsolutefluctuationin nT. Otherwiseit indicatesa relativefluctuationspecification,being Ø.Ùu�Æ ×BÂ�ÆzÚ .


crooldata

FORTRAN call crooldata(vrb, nobslev, olzv, oldepth,irc)

C crooldata(&vrb, &nobslev, &olzv[1],&oldepth[1], &irc);

Calculatingobservinglevelsinformationfrom datacontainedin acompresseddatafile header.

Sincetheheaderdatais of globalnature,thedatausedby this routinecorrespondsto themostrecentlyopenedcompressedfile.

Ar guments:


nobslev (Output, integer) Thenumberof observinglevels.

olzv (Output, doubleprecision,array(*)) Altitudes (in m) of the correspondingobservinglevels,from 1 to nobslev. Thecallingprogrammustensurethatthereis enoughspaceforthisarray.

oldepth (Output, doubleprecision,array(*)) Vertical atmosphericdepth(in g- cm0 ) of thecorrespondingobservinglevels,from 1 to nobslev. Thecallingprogrammustensurethatthereis enoughspacefor thisarray.



croreccount

FORTRAN call croreccount(channel, vrb, nrtype, nrec, irc)

C croreccount(&channel, &vrb, &nrtype[0], &nrec,&irc);

Countingtherecordsof a compressedfile startingfrom thefirst non-readrecord.Oncethefilewasscanned,thecorrespondingI/O channelis left in “end of file” status.

Ar guments:



nrtype (Output, integer) Thehighestrecordtypedefinedfor thefile (recordtypesrangefromzeroto nrtype).

nrec (Output, integer, array(0:nrtype)) For eachrecordtype,thenumberof recordsfound.No checkis madeto ensurethat the lengthof the array is enoughto storeall the dataitems.



crorecfind

FORTRAN okflag = crorecfind(channel, intype, vrb,infield1, rectype)

C okflag = crorecfind(&channel, &intype, &vrb,&infield1, &rectype);

Readingrecordsuntil getting a specifiedrecordtype. The compressedfile associatedwithchannel is scanneduntil a recordof type intype is found.

Ar guments:


intype (Input, integer) Recordtypeto find.


infield1 (Output, integer) If intype is zero, this variablecontainsthe currentvalue of thefirst integer field of the last scannedrecord(which will be, in general,a particlecode).Otherwiseit is setto zero.

rectype (Output, integer) Lastscannedrecordtypeandreturncode.This argumentcontainsthesameinformationasargumentir c of routinegetcrorecord. Noticethatin thecaseofsuccessfulreturn,rectypeis equalto intype.

Returnedvalue: (Logical) Trueif thelastrecordwassuccessfullyread.Falseotherwise(Endof file or I/O error).


crorecinfo

FORTRAN call crorecninfo(channel, poskey, ouflag, vrb,irc)

C crorecninfo(&channel, &poskey, &ouflag, &vrb,&irc);

Printing informationaboutthe total numberof recordswithin an alreadyopenedcompressedfile. Thefile is scannedstartingafterthelastrecordalreadyreadto countthenumberof recordsof eachtypethatwerewritten into it.

Ar guments:


poskey (Input, integer) Positioningkey. Thisparameterallows to controlthefile positioningafter returningfrom this routine: If zeroor negative the file remainspositionedat the“endof file” point, if 1 at thebeginningof data,andif greaterthan1, at thepositionfoundbeforethecall (This lastoptionmayeventuallyimply asignificantincreasein processingtime for very largefiles).

ouflag (Integer, input) Logicaloutputunit(s)selectionflag. Seeroutinecroheaderinfo.




crorecnumber

FORTRAN recno = crorecnumber(channel, vrb, irc)

C recno = crorecnumber(&channel, &vrb, &irc);

This function returnsthe current recordnumbercorrespondingto an alreadyopenedcom-pressedfile.

Ar guments:




Returnedvalue: (Integer) Therecordnumber. If thefile is not ready(closedor endof file),then �ÛU is returned.


crorecstrut

FORTRAN call crorecstruct(channel, nrtype, nintf, nrealf,irc)

C crorecstruct(&channel, &nrtype, &nintf, &nrealf,&irc);

Gettinginformationabouttherecordsof analreadyopenedcompressedfile.

Ar guments:


nrtype (Output, integer) Thehighestrecordtypedefinedfor thefile (recordtypesrangefromzeroto nrtype).

nintf (Output, integer, array(0:nrtype)) Numberof integerfieldscontainedat eachrecordtype,for recordtypesfrom zeroto nrtype. No checkis madeto ensurethatthelengthofthearrayis enoughto storeall thedataitems.

nrealf (Output, integer, array(0:nrtype)) Numberof real fields containedat eachrecordtype,for recordtypesfrom zeroto nrtype. No checkis madeto ensurethatthelengthofthearrayis enoughto storeall thedataitems.



crorewind

FORTRAN call crorewind(channel, vrb, irc)

C crorewind(&channel, &vrb, &irc);

“Rewinding” analreadyopenedcompressedfile. Thefile is positionedjustbeforethefirst datarecord.In otherwords,thefile is systemrewoundandits headeris re-scannedsothefile pointerremainslocatedat thebeginningof therecorddatastream.

Ar guments:





crospcode

FORTRAN isspecial = crospcode(pcode, splabel)

C isspecial = crospcode(&pcode, &splabel);

This logical functiondetermineswhetheror not a givenparticlecodecorrespondsto a specialprimaryparticle.

Ar guments:

pcode (Input, integer) Theparticlecodeto check.

splabel (Output, integer) Labelassociatedto thespecialparticle,or zeroif thecodedoesnotcorrespondsto a specialparticle.This variableis usefulfor furtherusewith otherlibraryroutines,andshouldnotbesetby thecallingprogram.

Returnedvalue: (Logical) True if the input codecorrespondsto a specialprimary particle.Falseotherwise.


crospmodinfo

FORTRAN call crospmodinfo(spname, spmodu, spml, sppars,sppl, irc)

C crospmodinfoc(&spname, &spmodu, &spml, &sppars,&sppl, &irc);

Retrieving informationabouttheexternalmoduleassociatedto a alreadydefinedspecialpar-ticle. Whenthis routine is usedto retrieve informationstoredin a compressedfile, the datareturnedcorrespondto themostrecentlyopenedcompressedfile.

Ar guments:

intdata (Input, string) Thenameof thespecialparticle.

spmodu (Output, string) The nameof the associatedmodule. The calling programmustprovide enoughspacefor this string.

spmodu (Output, integer) Lengthof stringspmodu.

sppars (Output, string) Stringcontainingtheparameterspassedto themodule. Thecallingprogrammustprovide enoughspacefor this string.

sppl (Output, integer) Lengthof stringsppars.


crospnames

FORTRAN call crospnames(nspp, spname)

C crospnamesc(&nspp, &spname[1]);

Retrieving thenamesof thecurrentlydefinedspecialparticles.Whenthis routineis usedto re-trieve informationstoredin acompressedfile, thedatareturnedcorrespondto themostrecentlyopenedcompressedfile.

Ar guments:

nspp (Input, integer) Thenumberof specialparticlesdefined.

spname (Output, string, array(*)) Array containingthenamesof thedefinedparticles.Thecallingprogrammustprovideenoughspacefor thisarray, andits elements(maximum16characterseach).


crotaskid

FORTRAN call crotaskid(taskname, tasknamelen,taskversion, startdate)

C crotaskidc(&taskname, &tasknamelen,&taskversion, &startdate);

Getting task nameand startingdatefor the task correspondingto the mostrecentlyopenedcompressedfile.

Ar guments:

taskname (Output, string) Thetaskname.Thecalling programmustensurethereis enoughspaceto storethestring.

tasknamelen (Output, integer) Lengthof taskname.

tasknameversion (Output, integer) Taskversion.

startdate (Output, string) Taskstartingdatein the format “dd/Mmm/yyyy hh:mm:ss”(20characters).


dumpfileversion

FORTRAN ivers = dumpfileversion()

C ivers = dumpfileversion();

ReturningtheAIRESversionassociatedwith thedumpfile thatwasmostrecentlyreadin (thiscanbedoneusingroutineloadumpfile).

Returnedvalue: (Integer) Thecorrespondingversionin integerformat(for examplethenum-ber 01040200for version1.4.2,01040201for version1.4.2a,etc.). If thereis an error,thenthereturnvalueis negative.


dumpfileversiono

FORTRAN ivers = dumpfileversiono()

C ivers = dumpfileversiono();

ReturningtheAIRESversionusedto write for thefirst time(theoriginalversion)thedumpfilethatwasmostrecentlyreadin (this canbedoneusingroutineloadumpfile).

Returnedvalue: (Integer) Thecorrespondingversionin integerformat(for examplethenum-ber 01040200for version1.4.2,01040201for version1.4.2a,etc.). If thereis an error,thenthereturnvalueis negative.


dumpinputdata0

FORTRAN call dumpinputdata0(intdata, realdata)

C dumpinputdata0(&intdata[1], &realdata[1]);

Copying into arrayssomeglobal input dataparametersstoredin the dumpfile that wasmostrecentlyreadin (this canbedoneusingroutine loadumpfile), thatarenot returnedby croin-putdata0.

Ar guments:

intdata (Output, integer, array(*)) Integer dataarray. The calling programmust provideenoughspacefor it. Thefollowing list describesthedifferentdataitems:

1 Totalnumberof showers.2 Numberof completedshowers.3 First shower number.

4-9 Reservedfor futureuse.10 Separateshowersintegerparameter.

realdata (Output, double precision, array(*)) Real dataarray. The calling programmustprovide enoughspacefor it. Thefollowing list describesthedifferentdataitems:

1- Reservedfor futureuse.


fitghf

FORTRAN call fitghf(bodata0, eodata0, depths,nallch, weights, ws, minnmax,nminratio, bodataeff, eodataeff,nmax, xmax, x0, lambda, sqsum,irc)

C fitghf(&bodata0, &eodata0, &depths[1],&nallch[1], &weights[1], &ws,&minnmax, &nminratio, &bodataeff,&eodataeff, &nmax, &xmax, &x0,&lambda, &sqsum, &irc);

Performinga 4-parameternonlinearleastsquaresfit to evaluatetheparameters{Û?�Aed , bc?�Aed ,b P and Ü of theGaisser-Hillas functionof equation(4.1). Thefit is doneusingtheLevenberg-Mardquardtalgorithm,asimplementedin thepublicdomainsoftwarelibrary Netlib [10].

Ar guments:

bodata0,eodata0 (Input, integer) Positive integer parametersdefining the numberof datapointsto usein thefit.

depths (Input, doubleprecision,array(eodata0)) Depthsof theobservinglevelsusedin thefit. Only therange(bodata0:eodata0) is used.

nallch (Input, doubleprecision,array(eodata0)) Numberof chargedparticlescrossingthedifferentlevels.Only therange(bodata0:eodata0) is used.

weights (Input, doubleprecision,array(eodata0)) Positive weightsto be assignedto eachoneof thedatapoints.Only therange(bodata0:eodata0) is used.

ws (Input, integer) If Ó��ÝjÞ¦ , the weightsareevaluatedinternally (proportionallyto thesquarerootof thenumberof particles).If Ó��ßj U they mustbeprovidedasinput data.IfÓ��ßjà¦ thearrayweights is notused.

minnmax (Input, doubleprecision) Thresholdvaluefor themaximumnumberof particlesintheinput dataset.Thefit is not performedif themaximumnumberof particlesis belowthisparameter. If minnmax is negative, it is takenaszero.

nminratio (Input, doubleprecision) Positiveparameterusedto determinetheendof thedataset. Must be equalor greaterthan5. Oncethe maximumof the dataset is found. thepointslocatedafterthis maximumup to thepoint wherethenumberof chargedparticlesis lessthanthemaximumdividednminratio . Theremainingpartof thedatais not takeninto accountin thefit. A similar analysisis performedwith thepointslocatedbeforethemaximum.Therecommendedvalueis 100. A very largevaluewill enforceinclusionofall thedataset.


bodataeff, eodataeff (Output, integer) Theactualrangeof datapointsusedin thefit.

nmax (Output,doubleprecision) Estimatednumberof chargedparticlesat theshower max-imum (parameter{Û?�Aed ). If no fit was possible,then the value coming from a directestimationfrom theinput datais returned.

xmax (Output, doubleprecision) Fittedpositionof theshower maximum, bc?�Aed , in g- cm0 .If no fit waspossible,thenthevaluecomingfrom a directestimationfrom theinput datais returned.

x0 (Output, doubleprecision) Fittedpositionof thepoint wheretheGaisser-Hillas functionis zero(parameterb P ), expressedin g- cm0 .

lambda (Output,doubleprecision) FittedparameterÜ , in g- cm0 .sqsum (Output,doubleprecision) Theresultingnormalizedsumof squares:

á j U{â{Û?�Aedãäå æ O

ç {ÝèÍé'ê]yzÎBw��Ò{Ýè�ë�ì�êhyzÎow�í 0{ è�ë�ì�ê yzÎBw V (D.1)

where { is the numberof datapointsusedin the fit, and { èÍé'ê ( { èîë�ìïê ) representthesetof particlenumbersgivenasinput (returnedfrom equation4.1 for thecorrespondingdepths).

ir c (Output, integer) Returncode.Zeromeansthatthefit wassuccessfullycompleted.


getcrorecord

FORTRAN okflag = getcrorecord(channel, intfields,realfields, altrec, vrb,irc)

C okflag = getcrorecord(&channel, &intfields[1],&realfields[1], &altrec,&vrb, &irc);

Readinga recordfrom acompresseddatafile alreadyopened.This routinecanbeusedto readrecordsfrom every kind of compressedfile: The routineautomaticallyprocessesthe recordswithout needingany user-level specificationbeyond file identity (parameterchannel). Thelogical returnedvalue(hereassignedto logical variableokflag) permitsdeterminingwhetheror not the readoperationwassuccessful.The characteristicsof the readrecordareinformedvia thereturncode(ir c), andthearraysintfields andrealfieldscontainthecorrespondingdataitems.Their contentsdependon thefile beingprocessedandon therecordtype.Theauxiliaryroutinescrofileinfo andcrofieldindexareusefulto processadequatelythereturneddataateachcase.

Ar guments:


intfields (Output, integer, array(*)) Integer fields of the last readrecord. This includesthenon-scaledinteger quantitiesand(in the last positions)the date-timespecification(s),ifany. The calling programmustprovide enoughspacefor this array(The minimum di-mensionis themaximumnumberof fields thatcanappearin a recordplus1). Positionsbeyond the last integer fields areusedasscratchworking space.The meaningof eachdataitem within thisarrayvarieswith theclassof file processedandwith therecordtype(seealsoargumentir c androutinecrofileinfo).

realfields (Output,doubleprecision,array(*)) Realfieldsof therecord.Thecallingprogrammustprovideenoughspacefor thisarray. Themeaningof eachdataitemwithin thisarrayvarieswith theclassof file processedandwith therecordtype(seealsoargumentir c androutinecrofileinfo).

altrec (Output, logical) True if thecorrespondingrecordtype is positive (alternative recordtype)Falseif therecordtypeis zero(default recordtype).

vrb (Input, integer) Verbositycontrol. If vrb is zeroor negative thenno erroror informativemessagesareprinted;error conditionsarecommunicatedto thecalling programvia thereturn code. If vrb is positive error messageswill be printed: �H¡_¢£j¤U meansthatmessageswill be printedeven with successfuloperations. �H¡_¢¥j§¦QV]X meansthat only


errormessageswill beprinted. �H¡_¢��¨X is similar to �H¡Z¢�jaX , but with theadditionalactionof stoppingtheprogramif a fatalerrortakesplace.

ir c (Output, integer) Returncode.0 meansthata recordwith zero(default) recordtypewassuccessfullyread. Î ( ÎÛ�ð2 ) meansthat an alternative recordof type Î wassuccessfullyread. �ÛU meansthatan end-of-fileconditionwasgot from the correspondingfile. Anyothervalueindicatesa readingerror(ir c equalsthesystemreturncodeplus10000).

Returnedvalue: (Logical) Trueif arecordwassuccessfullyread.Falseotherwise(Endof fileor I/O error).


getcrorectype

FORTRAN okflag = getcrorectype(channel, vrb, infield1,rectype)

C okflag = getcrorectype(&channel, &vrb, &infield1,&rectype);

Gettingtherecordtypeof the recordwhich is locatednext to the last readrecordof thecom-pressedfile identifiedby argumentchannel.

Theactionof thisroutineconsistsin readingthefirst partof therecordto obtaintherecordtype,andthenskip theremainingpartto positionthefile at theendof thecorrespondingrecord.Theuseof this routineis recommendedwhenever only the recordtype is needed,sinceit is fasterthan getcrorecord. Whenadditionaldataof an alreadyscannedrecordis required,routineregetcrorecord canbeusedto re-scanthelastprocessedone.

Ar guments:



infield1 (Output, integer) If rectype is zero, this variablecontainsthe currentvalueof thefirst integerfield of therecord(which is, in general,aparticlecode).Otherwiseit is settozero.

rectype (Output, integer) Recordtype and returncode. This argumentcontainsthe sameinformationasargumentir c of routinegetcrorecord.



getglobal

FORTRAN call getglobal(gvname, sdynsw, gvval, valen)

C getglobalc(&gvname, &sdynsw, &gvval, &valen);

Gettingthecurrentvalueof analreadydefinedglobalvarible. Whenthis routineis usedto re-trieve informationstoredin acompressedfile, thedatareturnedcorrespondto themostrecentlyopenedcompressedfile.

Ar guments:

gvname (Input, string) Nameof globalvariable.

sdynsw (Output, integer) Typeof variable:1 dynamic,2 static,0 if thevariableis undefined.

gvval (Output,string) Thestringcurrentlyassignedto thevariable.Thecallingprogrammustensureenoughspaceto storethestring.

valen (Output, integer) Lengthof gvval. valen is negative for undefinedvariables.


getinpint

FORTRAN value = getinpint(dirname)

C value = getinpintc(&dirname);

Getting the currentvalue for an integer (static) input parametercorrespondingto the mostrecentlyopenedcompressedfile. This routineis usedto getfrom thecurrentfile’sheaderthoseintegerinput parametersnot returnedby routinecroinputdata0 (seepage154).

Ar guments:

dir name (Input, string) Nameof the IDL directive associatedwith the parameter(canbeabbreviatedaccordinglywith therulesdescribedin appendixB).

Returnedvalue: (integer) The currentsettingfor the correspondingparameter. In caseoferrorthereturnedvalueis undefined.


getinpreal

FORTRAN value = getinpreal(dirname)

C value = getinprealc(&dirname);

Gettingthecurrentvaluefor a real (static)input parametercorrespondingto themostrecentlyopenedcompressedfile. This routine is usedto get from the currentfile’s headerthoserealinput parametersnot returnedby routinecroinputdata0 (seepage154).

Ar guments:


Returnedvalue: (doubleprecision) The currentsettingfor thecorrespondingparameter. Incaseof errorthereturnedvalueis undefined.


getinpstring

FORTRAN call getinpstring(dirname, value, slen)

C getinpstringc(&dirname, &value, &slen);

Gettingthecurrentvaluefor an input (static)character string correspondingto themostre-centlyopenedcompressedfile.

Ar guments:


value (Output, string) The currentparametervalue. The calling programmustensurethatthereis enoughspaceto storethestring.

slen (Output, integer) Lengthof thecurrentparametervalue.On error, slen is negative.


getinpswitch

FORTRAN value = getinpswitch(dirname)

C value = getinpswitchc(&dirname);

Gettingthecurrentvaluefor aninput (static)logical switch correspondingto themostrecentlyopenedcompressedfile. This routineis usedto getfrom thecurrentfile’s headerthoselogicalinput parametersnot returnedby routinecroinputdata0 (seepage154).

Ar guments:


Returnedvalue: (Logical) The currentsettingfor the correspondingparameter. In caseoferrorthereturnedvalueis undefined.


getlgtinit

FORTRAN call getlgtinit(channel, vrb, irc)

C getlgtinit(&channel, &vrb, &irc);

Initializing internaldataneededto processrecordsfrom compressedlongitudinalparticletrack-ing files by meansof routine getlgtrecord and relatedones. This routine shouldbe calledimmediatelyafteropeningthecorrespondingcompressedfile.

Ar guments:





getlgtrecord

FORTRAN okflag = getlgtrecord(channel, currol, updown,intfields, realfields,altrec, vrb, irc)

C okflag = getlgtrecord(&channel, &currol, &updown,&intfields[1],&realfields[1], &altrec,&vrb, &irc);

Readinga recordfrom a compressedlongitudinalparticletrackingfile andreturningthe readdatain a “level per level” basis. This routineinvokesgetcrorecord to get a recordfrom thecorrespondingcompressedfile whenit is necessary, andmustbeusedjointly with getlgtinit.

Ar guments:


currol (Output, integer) Observinglevel crossedby theparticle.

updown (Output, integer) Up-down indicator: 1 if theparticleis goingupwards, ��U other-wise.

intfields (Output, integer, array(*)) Integer fields of the last readrecord. This includesthenon-scaledinteger quantitiesand(in the last positions)the date-timespecification(s),ifany. The calling programmustprovide enoughspacefor this array(The minimum di-mensionis themaximumnumberof fields thatcanappearin a recordplus1). Positionsbeyond the last integer fields areusedasscratchworking space.The meaningof eachdataitem within thisarrayvarieswith theclassof file processedandwith therecordtype(seealsoargumentir c androutinecrofileinfo).

realfields (Output,doubleprecision,array(*)) Realfieldsof therecord.Thecallingprogrammustprovideenoughspacefor thisarray. Themeaningof eachdataitemwithin thisarrayvarieswith theclassof file processedandwith therecordtype(seealsoargumentir c androutinecrofileinfo).

altrec (Output, logical) True if thecorrespondingrecordtype is positive (alternative recordtype)Falseif therecordtypeis zero(default recordtype).

vrb (Input, integer) Verbositycontrol. If vrb is zeroor negative thenno erroror informativemessagesareprinted;error conditionsarecommunicatedto thecalling programvia thereturn code. If vrb is positive error messageswill be printed: �H¡_¢£j¤U meansthatmessageswill be printedeven with successfuloperations. �H¡_¢¥j§¦QV]X meansthat only


errormessageswill beprinted. �H¡_¢��¨X is similar to �H¡Z¢�jaX , but with theadditionalactionof stoppingtheprogramif a fatalerrortakesplace.

ir c (Output, integer) Returncode.0 meansthata recordwith zero(default) recordtypewassuccessfullyread. Î ( ÎÛ�ð2 ) meansthat an alternative recordof type Î wassuccessfullyread. �ÛU meansthatan end-of-fileconditionwasgot from the correspondingfile. Anyothervalueindicatesa readingerror(ir c equalsthesystemreturncodeplus10000).



ghfpars

FORTRAN call ghfpars(nmax, xmax, x0, lambda, vrb,irc)

C ghfpars(&nmax, &xmax, &x0, &lambda, &vrb,&irc);

Settingtheinternalquantitiesneededto work with theGaisser-Hillas function(equation(4.1))relatedroutines.

Ar guments:

nmax (Input, doubleprecision) Parameter{Û?�Aed of equation4.1.

xmax (Input, doubleprecision) Parameterbc?�Aed of equation4.1.

x0 (Input, doubleprecision) Parameterb P of equation4.1.

lambda (Input, doubleprecision) ParameterÜ of equation4.1.




ghfin

FORTRAN x = ghfin(np, prepost)

C x = ghfin(&np, &prepost);

Numericalevaluationof the inverseof theGaisser-Hillas function(equation(4.1)) for a givennumberof particlesnp. Thefour parameters{}?�Aed , bc?�Aed , b P , and Ü mustbespecifiedprevi-ouslyby meansof ghfpars.

Ar guments:

np (Input, doubleprecision) Thenumberof particles.If �®Ñòñ»2 or ��Ñó�»{}?�Aed , theresultisa largenegative number.

prepost (Input, integer) Integer parameterlabelingwhich of the two abscissasb hasto bereturned:If prepostis lessor equalto 0 then bôñàbc?�Aed ; otherwisebõ�àbc?�Aed . Noticethattheinverseof theGaisser-Hillas functionis bi-valuated.

Returnedvalue: (Double precision) The value of the inverseGaisser-Hillas function, ex-pressedin g- cm0 , thatis, x suchthatnp = ghfx(x).


ghfx

FORTRAN np = ghfx(x)

C np = ghfx(&x);

EvaluatingtheGaisser-Hillas function(equation(4.1))for agivendepthx. Thefour parameters{Û?�Aed , bc?�Aed , b P , and Ü mustbespecifiedpreviously by meansof ghfpars.

Ar guments:

x (Input, doubleprecision) Atmosphericdepthin g- cm0 .Returnedvalue: (Doubleprecision) Thevalueof thefunctionat thespecifiedx.


grandom

FORTRAN r = grandom()

C r = grandom();

This functioninvokestheAIRESrandomnumbergeneratorandreturnsapseudo-randomnum-berwith normalGaussiandistribution (zeromeanandunit standarddeviation). It is necessaryto initialize therandomseriescalling raninit beforeusingthis function.

Returnedvalue: (Doubleprecision) TheGaussianpseudo-randomnumber.


idlcheck

FORTRAN ikey = idlcheck(dirname)

C ikey = idlcheckc(&dirname);

Checkinga stringto seeif it matchesany of theIDL instructionscurrentlydefined,that is, theonescorrespondingto themostrecentlyopenedcompressedfile.

Ar guments:

dir name (Input, string) Nameof theIDL directive to bechecked(canbeabbreviatedaccord-ingly with therulesdescribedin appendixB).

Returnedvalue: (Integer) If anerroroccurs,thenthereturnedvaluewill benegative. Otherreturnvaluesarethefollowing:

0 Thestringdoesnotmatchany of thecurrentlyvalid IDL instructions.

1 The string matchesa directive belongingto the “basic” instructionsetwith no pa-rameter(s)associatedwith it, for exampleHelp.

2 Thestringmatchesa directive belongingto the “basic” instructionset. If thereis aparameterassociatedwith thedirective, thenit canbeobtainedby meansof routinecroinputdata0.

4 Thedirective correspondsto a real input parameter. Theparametercanberetrievedby meansof functiongetinpreal.

6 The directive correspondsto an integer input parameter. The parametercanbe re-trievedby meansof functiongetinpint.

8 The directive correspondsto a logical input parameter. The parametercanbe re-trievedby meansof functiongetinpswitch.

10 Thedirective correspondto astringinput parameter. Theparametercanberetrievedby meansof routinegetinpstring.


loadumpfile

FORTRAN call loadumpfile(wdir, taskname, vrb, irc)

C loadumpfilec(&wdir, &taskname, &vrb, &irc);

Readingthedumpfile associatedwith a giventask,andcopying into internalvariablesall theinformationcontainedwithin it.

Ar guments:

wdir (Input, characterstring) Thenameof thedirectorywherethefile is placed.It defaultsto thecurrentdirectorywhenblank.

taskname (Input, characterstring) Taskname,or dumpfile name.


ir c (Output, integer) Returncode.0 meanssuccessfulreturn.1 meanssuccessfulreturn,butthedumpfile wasnot createdusingthesameAIRES version.8 meansthatno dumpfile(in thesequencetaskname, taskname.adf, taskname.idf) exists. 12 meansinvalid filename.Otherreturncodescomefrom theadfor idf readroutines.


nuclcode

FORTRAN ncode = nuclcode(z, n, irc)

C ncode = nuclcode(&z, &n, &irc);

This routinereturnstheAIRES codeof a nucleusof , protonsand { neutrons,asdefinedinpage20.

Ar guments:

z (Input, integer) Thenumberof protonsin thenucleus.

n (Input, integer) Thenumberof neutronsin thenucleus.

ir c (Output, integer) Returncode.0 meansthata valid pair of input parametersym,öVh{Ýw wassuccessfullyprocessed.3 meansthat the nucleuscannotbe specifiedwith the AIRESsystem.5 meansthateither , or { areoutof allowedranges.

Returnedvalue: (Integer) Thenucleuscodeof equation(2.17).


nucldecode

FORTRAN call nucldecode(ncode, z, n, a)

C nucldecode(&ncode, &z, &n, &a);

This routinereturnsthe charge, neutronandmassnumberscorrespondingto a given AIRESnuclearcode(seepage20).

Ar guments:

ncode (Input, integer) TheAIRES nuclearcodeof equation(2.17).

z (Output, integer) Thenumberof protonsin thenucleus.

n (Output, integer) Thenumberof neutronsin thenucleus.

a (Output, integer) Themassnumber.


olcoord

FORTRAN call olcoord(nobslev, olzv, groundz, injz,zenith, azimuth, xaxis, yaxis,zaxis, tshift, mx, my, irc)

C olcoord(&nobslev, &olzv[1], &groundz,&injz, &zenith, &azimuth,&xaxis[1], &yaxis[1], &zaxis[1],&tshift[1], &mx[1], &my[1], &irc);

This routineevaluatesthecoordinatesof theintersectionsof observinglevel surfaceswith theshower axis, y>÷ P å Vhø P å V]ù P å w , ÎújûU�V^3^3^3ZVh{}| , the correspondingtime shifts, ü P å , andthe coeffi-cients,ý´þ å , ý´ÿ å , of theplanetangentto thesurfaceat theintersectionpoint:

ùú�Ýù P å jàý´þ å y>÷ ��÷ P å w�` ý´ÿ å yzøc�Òø P å whV Î®j1U�V^3^3^3Vh{~|Z3 (D.2)

Ar guments:

nobslev (Input, integer) Thenumberof observinglevels( {~| ).olzv (Input, doubleprecision,array(nobslev)) Altitudes (in m) of the correspondingob-

servinglevels.

groundz (Input, doubleprecision) Groundaltitude(in m).

injz (Input, doubleprecision) Injectionaltitude(in m).

zenith (Input, doubleprecision) Showerzenithangle(deg).

azimuth (Input, doubleprecision) Showerazimuthangle(deg).

xaxis,yaxis,zaxis (Output, doubleprecision,array(nobslev)) Respectively ÷ P å , ø P å andù P å , Îúj U�V^3^3^3Vh{ | , coordinates(in m) of the intersectionpointsbetweenthe observinglevel surfacesandtheshower axis.

tshift (Output, double precision, array(nobslev)) Observinglevels time shifts, ü P å , Î jU�V^3^3^3Vh{~| , (in ns),thatis, theamountof timeaparticlemoving at thespeedof light needsto go from theshower injectionpoint to correspondingintersectionpoint y>÷ P å Vhø P å V]ù P å w .

mx, my (Output, doubleprecision,array(nobslev)) Coefficientsof the planeswhich aretangentto theobservinglevelsandpassby thecorrespondingintersectionpoints.

ir c (Output, integer) Returncode.Zeromeanssuccessfulreturn.


olcrossed

FORTRAN call olcrossed(olkey, updown, firstol, lastol)

C olcrossed(&olkey, &updown, &firstol,&lastol);

This routinereconstructstheinformationcontainedin thecrossedobservinglevelskey, oneofthedataitemssavedat eachparticlerecordin any longitudinaltrackingcompressedfile.

This key encodesthe first and last crossedobservingobservinglevels and the direction ofmotion. The encodingformula definedin equation(4.6), where

�, Î�� and Î�� correspondto

olkey, firstol andlastol, respectively.

The routine returnsall the variablesof the right handside of equation(4.6). The variableassociatedto �� , updown is setin a slightly differentway: It is besetto 1 whentheparticlegoesupwards,andto �ÛU otherwise.

Ar guments:

olkey (Input, integer) Key with informationaboutthecrossedobservinglevels.

updown (Output, integer) Up-down indicator: 1 if theparticleis goingupwards, ��U other-wise.

firstol (Output, integer) Firstobservinglevel crossed( U�º�f¡Z�^Ï��º 74U^2 ).lastol (Output, integer) Lastobservinglevel crossed( U�º �>½¿�iÏ��Hº 74U^2 ).


olcrossedu

FORTRAN call olcrossedu(olkey, ux, uy, uz, firstol,lastol)

C olcrossedu(&olkey, &ux, &uy, &uz, &firstol,&lastol);

This routineis similar to olcrossed, but retrievestheinformationabouttheparticle’s directionof motion(upor down) in theform of anunitaryvector.

Ar guments:

olkey (Input, integer) Key with informationaboutthecrossedobservinglevels (Seeroutineolcrossed).

ux, uy (Input, doubleprecision) ÷ and ø componentsof theunitaryvectormarkingtheparti-cle’s directionof motion.

uz (Output, doubleprecision) ù componentof the directionof motion. Positive meansup-wardsmotion.

firstol (Output, integer) Firstobservinglevel crossed( U�º�f¡Z�^Ï��º 74U^2 ).lastol (Output, integer) Lastobservinglevel crossed( U�º �>½¿�iÏ��Hº 74U^2 ).


olsavemarked

FORTRAN ismarked = olsavemarked(obslev, vrb, irc)

C ismarked = olsavemarked(&obslev, &vrb, &irc);

Logical functionreturning“true” if anobservinglevel is markedto besaved into longitudinalfiles, “f alse”otherwise.An arbitrarysubsetof thedefinedobservinglevelscanbeselectedforinclusioninto the longitudinalcompressedfiles (seepage131); this functionallows to deter-mineif agivenobservinglevel wasor notmarkedat themomentof performingthesimulationsthatgeneratedthecorrespondingcompressedfile.

Ar guments:

obslev (Input, integer) Thenumberof observinglevel. If it is outof rangethereturnedvaluewill alwaysbe“f alse”.



Returnedvalue: (Logical) “true” if thelevel is markedfor file recording,“f alse”otherwise.


olv2slant

FORTRAN call olv2slant(nobslev, olxv, Xv0, zendis,zen1, zen2, groundz, olxs)

C olv2slant(&nobslev, &olxv[1], &Xv0, &zendis,&zen1, &zen2, &groundz, &olxs[1]);

Evaluatingtheslantdepthsof asetof observinglevels.Theslantdepthsarecalculatedalonganaxisstartingataltitudezground, for the“segment”thatendsatverticaldepthXv0 (Xv0 j 2 isthetop of theatmosphere).Theintegervariablezendisallows to selectamongfixed,sineandsine-cosinezenithangledistributions(seesection3.3.3).

Ar guments:

nobslev (Input, integer) Thenumberof observinglevels( {~| ).olxv (Input, doubleprecision,array(nobslev)) Verticalatmosphericdepths(in g- cm0 ) of

thecorrespondingobservinglevels.

Xv0 (Input, doubleprecision) Verticalatmosphericdepth(in g- cm0 ) of thepointmarkingtheendof theintegrationpath. If Xv0 is zero,thentheendof theintegrationpathis thetopof theatmosphere.

zendis (Input, integer) Zenith angledistribution switch: 0 – fixed zenith angle,1 – sinedistribution,2 – sine-cosinedistribution.

zen1,zen2 (Input, double precision) Minimum and maximumzenith angles(degrees). Ifzendisis 0, thenzen2is notusedandzen1givesthecorrespondingfixedzenithangle.

groundz (Input, doubleprecision) Groundaltitude(in m).

olxs (Output, doubleprecision,array(nobslev)) Slantatmosphericdepths(in g- cm0 ) ofthecorrespondingobservinglevels.


opencrofile

FORTRAN call opencrofile(wdir, filename, header1,logbase, vrb, channel, irc)

C opencrofilec(&wdir, &filename, &header1,&logbase, &vrb, &channel, &irc);

Openinga CIO file for reading.This routineperformsboththesystemopenoperationandfileheaderprocessingandchecking.

Ar guments:

wdir (Input, characterstring) Thenameof thedirectorywherethefile is placed.It defaultsto thecurrentdirectorywhenblank.

filename (Input, characterstring) Thenameof thefile to open.

header1 (Input, integer) Integerswitchto selectreading(greaterthanor equalto 0) or skip-ping (lessthan0) thefirst partof theheader.

logbase (Input, integer) Variabletocontrolthelogarithmicallyscaledfieldsof thefile records.If logbaseis lessthan2, thenthe returnedlogarithmswill benaturallogarithms.Other-wisebaselogbasewill bereturned(decimalonesif �>� ¾�¢H½¿��cj U^2 ).


channel (Output, integer) File identification. This variableshouldnot be changedby thecalling program. It mustbe usedasa parameterof the readingandclosingroutinesinorderto specifythecorrespondingfile.

ir c (Output, integer) Returncode. 0 meanssuccessfulreturn. 1 meanssuccessfulreturnobtainedwith a file thatwaswritten with a previous AIRES version. 10 meansthat thefile could be openednormally, but that it seemsnot to be a valid AIRES compresseddatafile, or is a corruptedfile; 12 invalid file header;14 not enoughsize in someofthe internalarrays;16 format incompatibilities. 20: too many compressedfiles alreadyopened. X�2�2àñ �z¡Z� ñ [�2�2 indicatesa versionincompatibility (whenprocessingfileswritten with otherAIRES version)or invalid versionfield (corruptheader).Any othervalueindicatesanopening/ header-readingerror(ir c equalsthesystemreturncodeplus10000).


raninit

FORTRAN call raninit(seed)

C raninit(&seed);

Initialization of the uniform pseudo-randomnumbergenerator.This routine mustbe calledbeforethefirst invocationof grandom, urandom, or urandomt.

Ar guments:

seed (Input, doubleprecision) Seedto initialize the randomseries.If seeddoesnot belongto the interval yz24ViU_w , thentheseedactuallyusedfor initialization is internallygeneratedusingtheelementarygeneratorclockrandom.


regetcrorecord

FORTRAN okflag = regetcrorecord(channel, intfields,realfields, altrec, vrb,irc)

C okflag = regetcrorecord(&channel, &intfields[1],&realfields[1], &altrec,&vrb, &irc);

Re-readingthecurrentrecord.Theinputandoutputparametersof this routineareequivalenttotherespective argumentsof routinegetcrorecord. Thedifferencebetweenthis routineandthementionedoneis thatregetcrorecord re-scansthelastreadrecordinsteadof advancingacrosstheinputfile. regetcrorecord is thoughtto beusedjointly with getcrorectype, crorecfind andotherrelatedprocedures.

Ar guments:


intfields (Output, integer, array(*)) Integer fields of the record. For a completedescriptionof thisargumentseeroutinegetcrorecord

realfields (Output, double precision, array(*)) Real fields of the record. For a completedescriptionof thisargumentseeroutinegetcrorecord

altrec (Output, logical) Alternative/default recordtypelabel.Seegetcrorecord


ir c (Output, integer) Returncode. For a completedescriptionof this argumentseeroutinegetcrorecord

Returnedvalue: (Logical) Trueif arecordwassuccessfullyre-read.Falseotherwise(EOForI/O error).


sp1stint

FORTRAN call sp1stint(csys, x1, y1, z1, irc)

C sp1stint(&csys, &x1, &y1, &z1, &irc);

Settingmanuallythe position of the first interaction. When using specialprimary particlesprocessedby externalmoduleswhich may inject more that a singleprimary, AIRES cannotdetermineautomaticallythe point wherethe first interactiontakes place,andwill take it asequalto the injection point unlessit is setexplicitly usingsp1stint. This routineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

csys (Input, integer) Parameterlabelingthe coordinatesystemused. ��i��Ôj£2 selectstheAIRES coordinatesystem. ��^��j£U selectstheshower axis-injectionpoint systemde-finedin section3.5.

x1, y1, z1 (Input, doubleprecision) Coordinatesof thefirst interactionpoint with respecttothechosencoordinatesystem(in meters).

ir c (Output, integer) Returncode.0 meansnormalreturn.


spaddnull

FORTRAN call spaddnull(pener, pwt, irc)

C spaddnull(&pener, &pwt, &irc);

Addinganull (unphysical)particleto thelist of primariesto bepassedfrom theexternalmoduleto themainsimulationprogram.This “particle” will not bepropagated,but its energy will beaddedto theunphysicalparticlecounterincludedin theshower energy balance.This routineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

pener (Input, doubleprecision) Energy (GeV).

pwt (Input, doubleprecision) Null particleweight.Must beequalor greaterthanone.



spaddp0

FORTRAN call spaddp0(pcode, pener, csys, ux, uy, uz,pwt, irc)

C spaddp0(&pcode, &pener, &csys, &ux, &uy,&uz, &pwt, &irc);

Adding a primaryparticleto thelist of primariesto bepassedfrom theexternalmoduleto themainsimulationprogram.Thisroutineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

pcode (Input, integer) Particlecode,accordinglywith theAIREScodingsystemdescribedinsection2.2.1(page20).

pener (Input, doubleprecision) Kinetic energy (GeV).


ux, uy, uz (Input, doubleprecision) Directionof motionwith respectto thechosencoordinatesystem.Thevector y�¸�LV]¸��.V]¸ �¿w doesnotneedto benormalized.

pwt (Input, doubleprecision) Particleweight.Mustbeequalor greaterthanone.

ir c (Output, integer) Returncode;canbeoneof thefollowing:

0 Theparticlewassuccessfullyadded.

8 Negative kineticenergy.

9 Particleweightlessthan1.

10 Thedirectionof motionis anull vector.

11 Invalid coordinatesystemspecification.


spaddpn

FORTRAN call spaddpn(n, pcode, pener, csys, ldu,uxyz, pwt, irc)

C spaddpn(&n, &pcode, &pener, &csys, &ldu,&uxyz[1][1], &pwt, &irc);

Addingasetof n primaryparticlesto thelist of primariesto bepassedfrom theexternalmoduleto themainsimulationprogram.This routineshouldbeusedonly within modulesdesignedtoprocessspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

n (Input, integer) Thenumberof particlesto addto thelist.

pcode (Input, integer, array(n)) Particlecodes,accordinglywith theAIRES codingsystemdescribedin section2.2.1(page20).

pener (Input, doubleprecision,array(n)) Kinetic energies(GeV).


ldu (Input, integer) Leadingdimensionof arrayuxyz; mustbeequalor greaterthan3.

uxyz (Input, doubleprecision,array(ldu,n)5) Directionsof motionwith respectto thechosencoordinatesystem.The vectors y�¸��yBU�VhÎBwhV]¸��y�¦QVhÎowhV]¸�� y��V'��w'w , Îúj U�V^3^3^3ZV�� , donotneedto benormalized.

pwt (Input, double precision, array(n)) Particle weights. The weightsmust be equalorgreaterthanone.


5If uxyz is definedin a C environment,thenits two dimensionsshouldbeswapped,i.e.,double uxyz[n][ldu].


speiend

FORTRAN call speiend(retcode)

C speiend(&retcode);

Closingthe interfacefor thespecialprimaryparticleexternalprocess.This routineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

retcode (Input, integer) Returncodeto passto themainsimulationprogram. ¡�JÏ��®�´jâ2meansnormalreturn.If retcodeis notzero,amessagewill beprintedandsavedin thelogfile (extension.lgf). 2²ñ * ¡Z�JÏ��®��*4ñ¥U^2 , U^2²º * ¡Z�JÏ��®��*Qñ ¦�2 , ¦�2²ºâ* ¡�JÏ��®��*\ñ X�2 ,and * ¡Z��Ï��*��§X�2 correspond,respectively, to information,warning,error andfatalmessages.


speigetmodname

FORTRAN call speigetmodname(mn, mnlen, mnfull, mnfullen)

C speigetmodnamec(&mn, &mnlen, &mnfull, &mnfullen);

Gettingthenameof themoduleinvoked by thesimulationprogram,that is, theonespecifiedin thedefinitionof thecorrespondingspecialparticle.This routineshouldbeusedonly withinmodulesdesignedto processspecialprimaries,and following the guidelinesof section3.5(page70).

Ar guments:

mn (Output, string ) Nameof externalmodule. The calling programmustensurethereisenoughspaceto storethestring.

mnlen (Output, integer) Lengthof externalmodulename.

mnfull (Output,string ) Full nameof externalmodule(Will bedifferentof mn if themodulewas placedwithin one of the directoriesspecifiedwith the InputPath directive. Thecallingprogrammustensurethereis enoughspaceto storethestring.

mnfullen (Output, integer) Lengthof full externalmodulename.


speigetpars

FORTRAN call speigetpars(parstring, pstrlen)

C speigetparsc(&parstring, &pstrlen);

Getting the parameterstring specifiedin the IDL instructionthat definesthe correspondingspecialparticle. This routineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

parstring (Output,string ) Parameterstring.Thecallingprogrammustensurethereis enoughspaceto storethestring.

pstrlen (Output, integer) Lengthof parameterstring.Zeroif therearenoparameters.


speimv

FORTRAN call speimv(mvnew, mvold)

C speimv(&mvnew, &mvold);

Settingand/orgetting the external macroversion. This routine shouldbe usedonly withinmodulesdesignedto processspecialprimaries,and following the guidelinesof section3.5(page70).

Ar guments:

mvnew (Input, integer) Macroversionnumber. Must beaninteger in therange T�U�V'5�7�W�X�5�7ZY .If mvnew is zero,thenthemacroversionis not set.

mvold (Output, integer) Macroversionnumbereffective at themomentof invoking therou-tine. This variablewill besetto zeroin thefirst call to speimv.


spinjpoint

FORTRAN call spinjpoint(csys, x0, y0, z0, tsw, t0beta,irc)

C spinjpoint(&csys, &x0, &y0, &z0, &tsw,&t0beta, &irc);

Setting the current injection point for primary particles. This routine shouldbe usedonlywithin modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:


x0, y0, z0 (Input, double precision) Coordinatesof the injection point with respectto thechosencoordinatesystem(in meters).

tsw (Input, integer) Injectiontime switch. If tsw is zerothent0beta is anabsoluteinjectiontime; if tsw is 1, thenthe injection time is setasthetime employed by a particlewhosespeedis Ï�� ¢f�JÏ½��²� to gofrom theoriginal injectionpoint to theintersectionpointof theshower axiswith theplaneorthogonalto thataxisandcontainingthepoint y� �HVo� ��V��w .

t0beta (Input, doubleprecision) Themeaningof thisargumentdependson thecurrentvalueof tsw. It canbe the absoluteinjection time (ns) (time at original injection is taken aszero);or thespeedof aparticledividedby � .



speistart

FORTRAN call speistart(showerno, primener, injpos,xvinj, zground, xvground,dgroundinj, uprim)

C speistart(&showerno, &primener, &injpos[1],&xvinj, &zground, &xvground,&dgroundinj, &uprim[1]);

Startingthe interfacefor thespecialprimaryparticleexternalprocess.This routineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

showerno (Output, integer) Currentshower number.

primener (Output,doubleprecision) Primaryenergy (GeV).

injpos (Output,doubleprecision,array(3)) Positionof theinitial injectionpointwith respectto theAIRES coordinatesystem(in meters).

xvinj (Output,doubleprecision) Verticalatmosphericdepthof theinjectionpoint(in g- cm0 ).zground (Output,doubleprecision) Altitude oggroundlevel (in m.a.s.l.).

xvground (Output, doubleprecision) Vertical atmosphericdepthof the groundsurface(ing- cm0 ).

dgroundinj (Output, doubleprecision) Distancefrom the injectionpoint to the intersectionbetweentheshower axisandthegroundsurface(in meters).

uprim (Output,doubleprecision,array(3)) Unitaryvectorin thedirectionof thestraightlinegoing from the injectionpoint towardsthe intersectionbetweentheshower axisandthegroundplane.


speitask

FORTRAN call speitask(taskn, tasklen, tver)

C speitaskc(&taskn, &tasklen, &tver);

Gettingthe currenttasknameandversion. This routineshouldbe usedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

taskn (Output,string ) Taskname.Thecallingprogrammustensurethereis enoughspacetostorethestring.

tasklen (Output, integer) Lengthof taskname.

tver (Output, integer) Tasknameversion.


spnshowers

FORTRAN call spnshowers(totsh, firstsh, lastsh)

C spnshowers(&totsh, &firstsh, &lastsh);

Gettingthecurrentvaluesof thefirst andlastshower, andtotalnumberof showers.Thisroutineshouldbeusedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

totsh (Output, integer) Total numberof showersfor thecurrenttask.

firstsh (Output, integer) Numberof first shower.

lasttsh (Output, integer) Numberof lastshower.


sprimname

FORTRAN call sprimname(pname, pnamelen)

C sprimnamec(&pname, &pnamelen);

Gettingthenameof thespecialprimaryparticlespecifiedin thecorrespondingIDL instruction.This routineshouldbe usedonly within modulesdesignedto processspecialprimaries,andfollowing theguidelinesof section3.5(page70).

Ar guments:

pname (Output, string) The nameof thespecialparticle. Thecalling programmustensurethereis enoughspaceto storethestring.

pnamelen (Output, integer) Lengthof particlename.


thisairesversion

FORTRAN iavers = thisairesversion()

C iavers = thisairesversion();

Returningthecurrentversionof theAIRES library.

Returnedvalue: (Integer) Thecorrespondingversionin integerformat(for examplethenum-ber01040200for version1.4.2,01040201for version1.4.2a,etc.).


urandom

FORTRAN r = urandom()

C r = urandom();

This functioninvokestheAIRESrandomnumbergeneratorandreturnsapseudo-randomnum-ber uniformly distributed in the interval T 24ViU_w . It is necessaryto initialize the randomseriescalling raninit beforeusingthis function.

Returnedvalue: (Doubleprecision) Theuniform pseudo-randomnumber.

urandomt

FORTRAN r = urandomt(threshold)

C r = urandomt(threshold);

This functioninvokestheAIRESrandomnumbergeneratorandreturnsapseudo-randomnum-beruniformly distributedin theinterval T ü'ViU_w , where ü is a specifiedthreshold( 2 º üFñ¨U ). Itis necessaryto initialize therandomseriescalling raninit beforeusingthis function.

Ar guments:

thr eshold (Input, doubleprecision) Thethresholdü .Returnedvalue: (Doubleprecision) Theuniform pseudo-randomnumber.


xslant

FORTRAN X = xslant(Xvert, Xv0, cozenith,zground)

C X = xslant(&Xvert, &Xv0, &cozenith,&zground);

Converting vertical atmosphericdepthsinto slantatmosphericdepths.This routineevaluatestheslantedpath(in g- cm0 ) of equation(2.8),starting(ending)at thepointwhoseverticaldepthis Xvert (Xv0). The inclination of the integrationpathis controlledby parameterscozenith(cosineof thezenithangle)andzground (altitude,in meters,of the intersectionbetweentheobliqueaxisandthe ù -axis),asillustratedin figure2.1(page12).

Ar guments:

Xvert (Input, doubleprecision) Verticalatmosphericdepth(in g- cm0 ) of thepoint markingthebeginningof theintegrationpath.Must bepositive.

Xv0 (Input, doubleprecision) Verticalatmosphericdepth(in g- cm0 ) of thepointmarkingtheendof theintegrationpath. If Xv0 is zero,thentheendof theintegrationpathis thetopof theatmosphere.If Xv0 correspondsto a point locatedbelow thepoint correspondingto Xvert ( � � � �� Q¡Ï ), thenthereturnedslantdepthwill benegative.

cozenith (Input, doubleprecision) Cosineof thezenithanglep (seefigure2.1)correspondingto theintegrationline. Must bein therange yz24ViU(Y .

zground (Input, doubleprecision) ù -coordinate(in meters)of theintersectionpointbetweentheobliqueaxisandthe ù -axis,which is normallycoincidentwith the“groundaltitude”.

Returnedvalue: (Doubleprecision) Theslantatmosphericdepthin g- cm0 ; or zeroin caseoferroror invalid argument.

Appendix E

Release notes

This appendixcontainsa brief summaryof the new developmentsthat are includedin the currentversionof AIRES (2.6.0),aswell asa descriptionof thedifferenceswith thepreviousreleaseof thesystem(2.4.0).

Thenumberin bracketsplacedafterdirective namesor library routinesindicatesthepagewherethecorrespondingdirective/routineis described.Example:TaskName(135).

E.1 Diff erences between AIRES 2.6.0 and AIRES 2.4.0

Bugs

Severalproblemswith AIRES 2.4.0simulationprogramweredetectedor reportedby severalusers.All theerrorsin theprogram’s code–mostlyminor bugs–werefixedandareno longerpresentin thecurrentversionof AIRES.Someof thosebugsare:

� Approximateprocessingof correctionsto the arrival times of heavy neutralparticleswhensaving theminto thegroundparticlesfile. Theproblemdoesnot affect thepropagationof theparticles.Thesaving algorithmhasbeenimprovedto overcomethisproblem.

� Correcteda minor bug in the muonic pair productionalgorithm, appearingfor low energymuonswith very smallprobability.

� Changedsomeincorrecterrormessagesappearingwhenopeninginexistentcompressedfiles.

� Fixedseveralminor technicalproblemsnotaffectingtheresultsof thesimulations.

� Fixedaseriesof minor bugsin theARS.

� Detectedandfixedsomeproblemsin theinstallationprocedurefor SGIsystems.

215

216 APPENDIX E. RELEASE NOTES

Algorithm modifications

Newhadronic models. SIBYLL 2.1[6] andQGSJET011 [7].

Nuclear interactions. Thenucleus-nucleuscrosssections,aswell asthenucleus-nucleuscollisionsarenow processedvia theexternalhadronicmodels.

Propagatednuclei. Thepropagationalgorithmscannow processnuclei beyond iron, with � up to36.

Other. Updatedvalueof Avogadro’s constant( ��! #"$"&%�'(%�)$)+*,%- $.0/ ), accordingto [34].

Input Directive Langua ge

Thenumberin bracketsplacedafterdirective namesindicatethe pagewherethecorrespondingdi-rective is described.

Newdir ectives.

1 ExtNucNucMFP (120).1 MinExtNucCollEner gy (126).1 TSSFile(136).

Dir ectivesrelatedto parameterswhich changedtheir default valuesor parameter ranges.

1 ThinningWF actor (135)

1 MinExtCollEner gy (126)

Output data

TSSfile. Thetasksummaryscriptfile is anew outputfile thatincludesgeneralinformationabouttheinputparametersof asimulationandsomeglobalobservables,in theformatKeyword = value,suitablefor processingwith otherprograms.For detailsseesection4.1.3(page81).

AIRES Runner System

TheARSincludesnow supportfor aBeforeProcessmacro.For detailsseesection5.2.2(page103).

1NOTE on the QGSJET VERSION: Thenew versionof QGSJETrequiresa long seriesof initialization calculationsrequiring several hours of CPU time. All the dataproducedduring the initialization phaseare saved into two files,namedQGSDAT01 andSECTNU, andcanbe recoveredfrom themin otherinvocationsof the package.It is thereforerecommendedto keepsuchfiles andreusethemin othersimulationsto avoid long delaysdueto QGSJETinitialization.

APPENDIX E. RELEASE NOTES 217

E.2 Diff erences between AIRES 2.4.0 and AIRES 2.2.1

Bugs

A numberof problemswith AIRES 2.2.1simulationprogramweredetectedor reportedby severalusers.All theerrorsin theprogram’s code–mostlyminorbugs–werefixedandareno longerpresentin thecurrentversionof AIRES.Someof thosebugsare:

1 Incorrectprocessingof a fractionof low energy neutrons.Wasfixed.

1 Slightmodificationin 2435276 annihilationand 2438296 bremsstrahlungprocessesto properlyman-agethecaseof very low primaryenergies.

1 Injectedspecialprimariesarenow checkedto verify thattheinjectionpoint is above thegroundlevel.

1 Minor bug in xslantlibrary function,relatedto :�; initialization. Wasfixed.

1 Extendedthecompressedfile managementroutinesto supportnegative ASCII charactercodes(asreturnedby recentimplementationsof g77compilerlibraries).

1 Theshower CPUtime is now correctlystoredin the“end of shower” recordsof multi-showerfiles.

Algorithm modifications

Muon propagation. The processesof muonbremsstrahlungandmuonic pair productionarenowtakeninto accountby AIRESpropagatingengine.

IGRF model. TheIGRF 2000datasetis theonecurrentlyusedto evaluatethegeomagneticfield.

Hadronic collisions. Completelynew versionof the Hillas splitting algorithm, tunedto produceeffective approximationsof moreinvolved models.Low energy crosssectionsarecalculatedfrom fits to experimentaldata.

Particle propagation. Codehasbeenaddedto fully propagate< baryons.Improved mesondecayprocedures.

Electromagneticprocedures. Exhaustive checkof thealgorithmsfor electromagneticprocesses.

Low energy particles. Introducednew IDL instructionsForceLowEDecays(122)andForceLowEAnnihilation (121) to allow controllingwhetheror not low energy particlesmustbeforcedto decaysor annihilation.

Thinning. Separatedweightfactorsfor electromagneticandheavy particles.

Other. A lot of minor improvementsin algorithmsthoughtheentirecodeandlibrary. Toomany andtoomuchtechnicalfor adetailedlist.

218 APPENDIX E. RELEASE NOTES

Installation procedure

Theinstallationscriptsweresubstantiallyimproved. Reportedproblemsrelatedwith theinstallationof AIRES 2.2.1have beensolved.

Someof thedefault settingsin theconfigfile have beenchanged.

Input Directive Langua ge

Thenumberin bracketsplacedafterdirective namesindicatethe pagewherethecorrespondingdi-rective is described.

Newfeatures.

1 Supportfor definingglobal variablesthatcaneitherbeusedwithin theIDL input streamor passedto theoutputfilesor externalmodules.Seesection3.2.5(page50).1 New supportedunits: inches(in), feet (ft ), yards(yd), miles (mi), andJoules(J). Seetable3.1(page49).

Newdir ectives.

1 Brackets(116).1 DelGlobal (117).1 EMtoHadr onWFRatio (119).1 ForceLowEAnnihilation (121).1 ForceLowEDecays(122).1 Import (124).1 MuonBr emsstrahlung(127).1 SetGlobal(133).

Dir ectivesno longer supported.

1 HadronCutEnergy. ObsoleteHillas splitting algorithmparameter. It hasno equivalentin thecurrentimplementationof thealgorithm.1 HeavyMineko. Parameterof the heavy particleknock-onalgorithm. The currentver-sionof thealgorithmusesonly compiletime parametersthatgenerallydo not needto bechangedby theuser.

Dir ectivesrelatedto parameterswhich changedtheir default valuesor parameter ranges.

1 PrimaryEner gy (129)1 ElectronCutEnergy (118)1 ElectronRoughCut (118)

APPENDIX E. RELEASE NOTES 219

1 GammaCutEnergy (122)1 GammaRoughCut(122)1 MesonCutEnergy (125)1 MuonCutEnergy (127)1 NuclCutEnergy (127)

Output data

Output tables. ThecurrentAIRES versionincludes48 new longitudinaldevelopmenttablescorre-spondingto thefollowing observables:

1 Numberof low energy particlesversusatmosphericdepth.1 Energy of low energy particlesversusatmosphericdepth.1 Depositedenergy (ionization)versusatmosphericdepth.

All theAIRESoutputtablesarelistedin appendixC

Appendix F

AIRES Histor y

This appendixbriefly summarizesthe history of the AIRES simulationsystem,startingfrom thecurrentversion(2.6.0)dated11/July/2002,backwardsto thefirst public release(version1.2.0)dated03/May/1997.

AIRES version 2.6.0 (11/Jul/2002).

This versionof AIRES consistsof about670routinesaddingup to morethan94,000linesof sourcecode.

Features.

1. New versionof SIBYLL (SIBYLL 2.1)hadronicmodel.

2. New versionof QGSJET(QGSJET01)hadronicmodel.

3. Nucleus-nucleuscrosssectionsandnuclearfragmentationarenow processedvia theexternalhadronicpackages(SIBYLL or QGSJET).

4. Thealgorithmsaving groundparticlesinto compressedfileswereimprovedto exactly accountthearrival timesof heavy neutralparticleslike neutrons.

5. Nuclearcodeswereextendedbeyondiron, up to �>=@?$� .6. Thesimulationandsummaryprogramscangeneratea tasksummaryscript file (extension.tss)

containingthe most relevant dataassociatedwith the simulations,in the format Keyword =value, suitablefor processingby otherprograms.

7. Completerevision of the AIRES RunnerSystem,focusedon improving the capacityof theSystemto copewith largescalecomputations.

8. TheAIRES runnerscriptsnow supporttheinclusionof a BeforeProcessmacro.

220

APPENDIX F. AIRES HISTORY 221

9. New modulesaddedto theAIRESobjectlibrary, in particularsomeroutinesfor easierprocess-ing of longitudinalparticletrackingfiles.

10. Revisionof theuser’s manualandinclusionof several issuesthatwereintroducedat theprevi-ousreleaseof AIRESwith pendingdocumentation.

11. Additionally, severalminor changes,improvements,and-of course-correctionsof bugs!

AIRES version 2.4.0 (19/Oct/2001).


Features.

1. New versionof thesplitting algorithmusedto processlow energy hadronicinteractions.Thisnew versionwastunedto effectively emulatewell-known interactionmodels.

2. Low energy crosssectionsarenow evaluatedusingfits to experimentaldata.

3. Improvedproceduresfor A -nucleuscollisions.

4. Muon propagationnow takesinto accountmuonbremsstrahlungandmuonicpair production.Thenew algorithmsarebasedin thetheoryby Kokoulin andPetrukhin[18].

5. New improvedprocedureto treatknock-onelectronsgeneratedby heavy chargedparticles.

6. Full propagationof < baryons.

7. Improvedproceduresfor mesonandbaryondecay.

8. Exhaustive revision of theelectromagneticshower engine.

9. The thinning algorithmpossessnow two maximumweight parameters,respectively for elec-tromagnetic( A , 2 3 , 2 6 ) andheavy particles.

10. New IGRF 2000datasetusedto estimategeomagneticfield.

11. 48 new longitudinaldevelopmenttablescorrespondingto the following observables:Numberof low energy particlesversusatmosphericdepth;Energy of low energy particlesversusatmo-sphericdepth;depositedenergy (ionization)versusatmosphericdepth.

12. Improvedprocedurefor updatingidf andcompressedfiles, thatpermitsmorestableoperationduringvery long runs.

13. Many new modulesin theAIRES library.

222 APPENDIX F. AIRES HISTORY

14. Global variablescanbedefinedwithin the input data. Suchvariablescanbeusedfor text re-placementwithin theinputfile and/orbepassedtoexternalanalysisorspecialprimarymodules.

15. New length(inches,feet,yards,andmiles)andenergy (Joules)unitssupported.ThestandardkeV replacestheold KeV which is maintainedasvalid for backwardscompatibility.

16. Additionally, lotsof minor changes,improvements,and-of course-correctionsof bugs!

AIRES version 2.2.1 (23/Dec/1999).

Functionallyequivalentto version2.2.0.A bug in the QGSJETinterface (Diffractive interactionswere mistakenly disabled)hasbeen

fixed.

AIRES version 2.2.0a (26/Nov/1999).

Functionallyequivalentto version2.2.0.A bug in therecentlydevelopedinterfacefor processingspecialprimarieshasbeenfixed.

AIRES version 2.2.0 (15/Nov/1999).


Features.

1. An improvedparameterizationof the 2435276 lossesin air.

2. A “resamplingalgorithm”whichselectively savesparticleslocatedneartheshoweraxis,capa-ble of reducingsubstantiallythesizesof thecompressedparticlefiles.

3. An improvementin thealgorithmto process< baryonsgeneratedby QGSJET.A relatedbugaffectingnoticeablyabout1%of theshowershasbeenfixed.

4. The AIRES kernel is now capableof invoking external, user-written, programsto generatesetsof particlesto beinjectedin thestacksbeforestartingthesimulationof thecorrespondingshower. This kind of primary particleprocessing,called“specialprimary particles”wasde-velopedfor severalpurposes,for example,processingthefirst interactionof “exotic” primarieslikeneutrinos,includingall theparticlesgeneratedby ultra-highenergy gammarayconversionin thegeomagneticfield beforereachingtheatmosphere,etc.

5. Upgradedversionof QGSJET.

6. Importantextensionof theAIRESobjectlibrary, includingaseriesof utilities to processspecialprimaries.



AIRES version 2.0.0 (relaunc hed) (06/May/1999).

Thiscorrespondsto a “patched”releaseof version2.0.0,including:

1. Minor correctionsto theuser’s manual.

2. Modified lowestvaluesfor the cut energiescontrolledby directivesElectronRoughCut andGammaRoughCutthatcanbeaslow as50 keV.

3. Correctedbug in Air esIDF2ADF.

AIRES version 2.0.0 (26/Apr/1999).


Features.

1. A completesetof optionsfor the hadronicmeanfree paths(or crosssections.The usercanselectamongStandard(or MOCCA), Bartol,QGSJETandSIBYLL hadronicmeanfreepaths,independentlyof theexternalcollisionalgorithm(QGSJETor SIBYLL) beingused.

2. A morerecentversionof theSIBYLL package(1.6) replacestheold 1.5versionusedin previ-ousreleasesof AIRES.

3. Thepropagatingprocedureswereexpandedto includefull kaonand B mesonpropagation.

4. The algorithmsfor calculationof energy lossesduring the longitudinal and groundparticlerecordinghave beennoticeablyimproved.

5. Thestatisticalthinningalgorithmhasbeenmodified.Thenew procedures,identifiedas“AIRESextendedthinning algorithm”, allows to put a strict upperboundto the maximumstatisticalweightthataparticleentrycanhave.

6. Thestackmanagementprocedureshave beenimprovedto makeamoreefficientuseof scratchspace. This producesa noticeableincreasein the performanceof the AIRES systemwhenprocessingshowersin extremelyhardthinningconditions.

7. Longitudinal, lateral, energy and time distribution tablescannow be saved in a per showerbasis,allowing the userto retrieve full informationon particularshowersusingthe standardfeaturesof thesummaryprogram.This featurecanbedisabledwhennecessary.


8. Two new outputdatatables,namely, “First interactiondepthandprimaryenergy versusshowernumber”and“Zenith andazimuthanglesversusshower number”.

9. All theatmosphericdepthsappearingin thelongitudinaldevelopmenttablesand/orpershowertablescannow beexpressedalsoasslantdepths.

10. All the datageneratedduring the simulations,which is storedin the (binary) internaldumpfile (IDF), can now be written in portableformat into a portable(ASCII) dump file (ADF)which canbe written whenfinishing a simulationtask. Additionally, a converting program,Air esIDF2ADF, is providedto convert any existing IDF file into ADF format.

11. The randomnumbergeneratorcannow be initialized taking the seedfrom an alreadyexis-tent IDF file correspondingto a previous task. This is mostuseful for reproducing(bitwise)simulationjobswhennecessary.

12. The AIRES object library was againexpanded,including a seriesof new modulesto easeAIRES outputmanagement.

13. Themodulesof theAIRES Runnersystemhave beenextensively revisedandimproved.

14. This distribution includesa new section,namely, cerntools,consistingof a seriesof PAWmacroscapableof downloadingAIRESoutputdatadirectly from within thisanalysisprogram.

15. The installationprocedureincludesa new platformoption: ALPHA workstationswith LinuxOS.

16. Thecompilingoptionsfor DECALPHA andHPworkstationsweremodifiedtoovercomesomecompilingandrunningproblemsthatwerepresentin pastreleasesof AIRES.


AIRES version 1.4.2a (18/Aug/1998).

Thisversionis functionallysimilar to version1.4.2.Thecodeincorporatescorrectionsto someminorbugs.

AIRES version 1.4.2 (18/Jun/1998).



Features.

1. TheUser’sManualwasrevisedandexpanded.Thesummaryandintroductionwerecompletelyrewritten. In particular, a moreprecisedescriptionof therelationexistingbetweenAIRES andMOCCA wasmade.

2. TheLPM effect algorithmswerecompletelyrewritten. Thenew proceduresemulateMigdal’stheory including the effect of dielectricsuppression.The old routineswerenot correct(theerrorswereinheritedfrom MOCCA’s procedures),andthereforeit is recommendedto re-runsimulationsdonewith olderversionsof AIRES atprimaryenergieslargerthan %- �CED eV.

3. Thenumberof observinglevels to beincludedin the longitudinaltrackingparticlefile canbenow controlledby meansof IDL directives.

4. Therearea few new routinesin theAIRES library.

5. Addedsupportfor unweightedtables.

6. Fixedbug affecting thearrival time distribution undercertaincircumstances.Many thankstoPierreBilloir andXavier Bertou(LPNHE,Paris,France).

7. Lotsof minor technicalimprovementsin thesimulationprograms,AIRESRunnerSystem,etc.

AIRES version 1.4.0 (29/Jan/1998).


Features.

1. The curvatureof the earthis taken into accountto evaluateparticle pathsand altitude FHGatmosphericdepthconversions.

2. Improvedlost particlealgorithms.This, togetherwith (1) allow for reliableprocessingof non-verticalshowersat all zenithangles,eventhequasi-horizontalones.

3. New compressedoutputfiles, andcompressedfiles options:Full longitudinalfile, and”largerecord”files thatallow for morecompleteparticleproperties.

4. New optionsfor printing andexporting tables: lL , allowing to get normalizedI#JLK9I�MON PQ�SR orI#JLK9I#MST$U CEV PQ�SR listings.

5. Special–nonprintable–characters(tabs,for example),cannow beincludedwithin IDL direc-tives.


6. More restrictive boundsfor primaryenergy: Must bein therange WS%YX[Z-\L]�%- $.�?^Z-\`_ , andmustbegreaterthanall thecut energies.

7. Both SIBYLL andBartol MFP’s arenow enabledby default. Theold defaultswereSIBYLLOn andBartol Off .

8. TheAIRES objectlibrary wassubstantiallyenlargedwith new routinescallablefrom analysisprograms.This includesalsointerfaceroutinesto permitprocessingcompressedfiles from aCenvironment.

9. Correctedminor bug in input datasummary(primaryenergy printing).

10. Correctedminor bug in roundingalgorithmusedin floatingpointnumbersencodingroutines.

11. Fixed bug in the algorithmfor countingparticlesduring the longitudinaldevelopmentof theshower. Thebug affectedparticlenumbersin runswith very high energy thresholds(1 GeV orso).Many thanksto RicardoVazquez(Universityof SaoPaulo,Brazil).

12. Fixed bug in the algorithmto set the depthof first interactionfor showerswith electronpri-maries.Many thanksto PierreBilloir (LPNHE,Paris,France).

13. Fixedbug in the“All neutralparticles”tablescalculations.Many thanksto IvoneAlbuquerque(U. of Chicago,USA).

14. Tasknameswith underscores(“ ”) can now be properlyprocessedusing the LaTeX option(Problempointedoutby PierreBilloir).

15. AddedLPM effectOn/Off switch.

16. Geomagneticfield included.Thegeomagneticfield canbespecifiedeitherexplicitly (giventhemodulusandorientationof B) or implicitly indicatingthegeographicalcoordinatesandaltitudeof thesite(in thiscasetheIGRFmodelis usedto evaluatethemagneticfield). Fluctuationsaresupportedaswell.

17. QGSJETinteractionmodelincluded.Some“approximations”hadto bedone,however: Kaonsandothermesonsnot treatedby AIRES aretreatedaspions. Thenuclearfragmentationalgo-rithm of QGSJETis notused.

18. Improvedmethodto evaluateXmaxandNmax.Now a four-parameterfit is used.

AIRES version 1.2.0 (30/Apr/1997).



The first public versionof AIRES packageincludesmany featuresof the well-known programMOCCA for air shower simulation.SIBYLL 1.5externalcollision packageis included.Otherchar-acteristicsare:Energy longitudinaldevelopment,compressedparticlefiles,brief documentation,etc.

References

[1] A. M. Hillas, Nucl.Phys.B (Proc. Suppl.),52B, 29 (1997);A. M. Hillas, Proc.19thICRC(LaJolla), 1, 155(1985).

[2] S.J.Sciutto,AIRES:A minimumdocument,AugertechnicalnoteGAP-97-029(1997).

[3] M. T. Dova and S. J. Sciutto, Air ShowerSimulations:ComparisonBetweenAIRES andMOCCA,AugertechnicalnoteGAP-97-053(1997).

[4] A. M. Hillas, Proc.of theParis Workshopon Cascadesimulations,J.Linsley andA. M. Hillas(eds.),p 39 (1981).

[5] M. Kobal,A. Filipcic andD. Zavrtanik, Auger technicalnotesGAP-98-001andGAP-98-058(1998).

[6] R. Engel,T. K. Gaisser, T. Stanev, Proc.26thICRC(Utah),1, 415(1999).

[7] N. N. Kalmykov andS. S.Ostapchenko, Yad.Fiz., 56, 105(1993);Phys.At. Nucl.,56, (3) 346(1993);N. N. Kalmykov, S. S. Ostapchenko andA. I. Pavlov, Bull. Russ.Acad.Sci.(Physics),58, 1966(1994).

[8] The data,software anddocumentationrelatedwith the InternationalGeomagneticReferenceFieldaredistributedby theNationalGeophysicalDataCenter, Boulder(CO),USA, andcanbeobtainedelectronicallyat thefollowing Webaddress:www.ngdc.noaa.gov.

[9] R. T. Fletcher, T. K. Gaisser, P. Lipari andT. Stanev, Phys.Rev. D, 50, 5710(1994);J.Engel,T.K. Gaisser, P. Lipari andT. Stanev, Phys.Rev. D, 46, 5013(1992).

[10] NETLIB is a public collection of mathematicalsoftware,papers,and databases,that can beaccessedthroughInternet,at theWorld Wide Webaddresswww.netlib.org.

[11] CERNProgramlibrary LongWriteupQ121(1995).

[12] S. J. Sciutto,AIRESusers guide and referencemanual, version1.4.2,Auger technicalnoteGAP-98-032(1998).

228

REFERENCES 229

[13] NationalAerospaceAdministration(NASA), NationalOceanicandAtmosphericAdministra-tion (NOAA) andUSAir Force,USstandard atmosphere 1976,NASA technicalreportNASA-TM-X-74335,NOAA technicalreportNOAA-S/T-76-1562(1976).

[14] R. C. Weast(editor),CRCHandbookof ChemistryandPhysics,61stedition,pp F206– F213,CRCPress,BocaRaton(FL, USA) (1981).

[15] B. Rossi,High-energy particles,Prentice-Hall,New Jersey (USA) (1956).

[16] We werenot ableto find official referencesrelatedwith Linsley’s standardatmospheremodel.References[1, 30] containinformationaboutparameterizationdata.

[17] A. Cillis andS.J.Sciutto,J. Phys.G, 26, 309-321(2000).

[18] A. Cillis andS.J.Sciutto,Phys.Rev. D, 64, 013010(2001).

[19] A. B. Migdal, Phys.Rev., 103, 1811(1956).

[20] A. Cillis, C. A. Garcıa Canal,H. FanchiottiandS.J.Sciutto,Phys.Rev. D, 59, 113012(1999).

[21] D. Heck,privatecommunication.

[22] T. K. Gaisser, CosmicRaysand Particle Physics,CambridgeUniversity Press,Cambridge(1992).

[23] S.J.Sciutto,in preparation.

[24] L. D. LandauandI. Ya.Pomeranchuk,Dokl. Akad.NaukSSSR,92, 535,735(1953).

[25] S.Klein, preprinthep-ph/9820442(1998).

[26] I. Vattulainen,T. Ala-Nissila,K. Kankaala,Phys.Rev. Lett.73, 2513(1994).

[27] S.J.Sciutto,in preparation.

[28] V. S. Berezinskiı, et. al., V. L. Ginzburg (editor),Astrophysicsof cosmicrays,North-Holland(1990).

[29] T. K. GaisserandA. M Hillas, Proc.15thICRC(Plovdiv),8, 353(1977).

[30] D. Heck,J.Knapp,J.N.Capdevielle, G. Schatz,andT. Thouw, ForschungszentrumKarlsruhe,ReportFZKA 6019(1998).

[31] P. Billoir , privatecommunication.

[32] Particle DataGroup,C. Casoet. al., TheEuropeanPhysicalJournal, C3, 1 (1998);website:www-pdg.lbl.gov.

230 REFERENCES

[33] CERNProgramlibrary LongWriteupW5013(1994).

[34] ParticleDataGroup,D. E. Groomet.al., TheEuropeanPhysicalJournal,C15, 1 (2000);web-site:www-pdg.lbl.gov.

Index

Pagenumbersin boldfacerepresentthedefinitionor themainsourceof informationaboutwhateveris beingindexed.

ADF or adf,seeinternaldumpfile, portableformatAIRES

history, 220installation,9, 109tableof features,4

AIREScoordinatesystem,11,12,19,62,72,74,76,129,199,201,202,207,208

AIRESfile directories,60export directory, 60,60, 121globaldirectory, 60, 107,121outputdirectory, 60, 121scratchdirectory, 60,60, 121working directory, 60,60, 103,104,115,124

AIRESIDF to ADF convertingprogram,5, 107,108,223,224

AIRESobjectlibrary, 2, 75,83,94,112,144,221,222,224,225

C interface,94,144cioclose, 98,145cioclose1, 98,145ciorinit, 94,99,146ciorshutdown, 98,147clockrandom, 148, 197crofieldindex, 99,149crofileinfo, 97,150crofileversion, 96,151crogotorec, 100,144,152croheaderinfo, 96,153croinputdata0, 96,154, 169,187crooldata, 100,156croreccount, 98,157crorecfind, 100,158crorecinfo, 98,159crorecnumber, 100,160crorecstrut, 97,161crorewind, 100,162crospcode, 84,100,163

crospmodinfo, 100,164crospnames, 165crotaskid, 96,166dumpfileversion, 97,167dumpfileversiono, 168dumpinputdata0, 97,169fitghf, 100,170getcrorecord, 97–99,172, 181getcrorectype, 100,174getglobal, 96,175getinpint, 96,176, 187getinpreal, 96,177, 187getinpstring, 96,178, 187getinpswitch, 96,179, 187getlgtinit, 98,180, 181getlgtrecord, 98,180,181ghfin, 100,184ghfpars, 100,183, 184,185ghfx, 100,185grandom, 100,186, 197idlcheck, 96,187loadumpfile, 96,167–169,188nuclcode, 75,189nucldecode, 190olcoord, 100,191olcrossed, 100,192olcrossedu, 100,193olsavemarked, 100,194olv2slant, 100,195opencrofile, 96,99,144,196raninit, 100,186,197, 213regetcrorecord, 100,174,198sp1stint, 76,199spaddnull, 75,200spaddp0, 72,73,75,201spaddpn, 75,202speiend, 72–74,76,203speigetmodname, 75,204speigetpars, 75,205speimv, 76,206

231

232 INDEX

speistart, 72–76,208speitask, 75,209spinjpoint, 76,207spnshowers, 75,210sprimname, 75,211thisairesversion, 96,212urandom, 100,197,213urandomt, 73,74,100,197,213xslant, 100,214

AIRESparticlecodes,20, 21,73,94,146,201,202

AIRESRunnerSystem,v, 5, 48,101,216,220,225

commandsairescheck, 101airesexport, 106aireskill, 103aireslaunch, 102,104airesstatus, 102airesstop, 103airestask, 102,105airesuntask, 103mkairesspool, 105rmairesspool, 105

AIRESsitelibrary, 48,64,115,123,134AIRESsummaryprogram,vi, 2, 5, 45,57,77,79,

107,114Air esIDF2ADF, seeAIRESIDF to ADF

convertingprogram.airesrc initialization file, 101,102,106,111Air esSry, seeAIRES summaryprogramalternativeprimaries,seespecialprimaryparticlesarrival time distributions,67ARSo ars,seeAIRES RunnerSystemASCII dumpfile, seeinternaldumpfile, portable

formatatmosphericdepth,15,116

slant,17,17, 18,100,195,214,224vertical,15,27,87,89

backwardscompatibility, 77,84bremsstrahlung,v, 3, 4, 22,23,118

cioclose, seeAIRESobjectlibrary.cioclose1, seeAIRES objectlibrary.ciorinit, seeAIRESobjectlibrary.ciorshutdown, seeAIRES objectlibrary.clockrandom, seeAIRES objectlibrary.commentcharactersin outputfiles,changing,80,

81,117

compressedoutputfiles,vi, 2, 5, 8, 9, 53,57,60,76,83,112,132,133,144,225

Comptoneffect,v, 3, 4, 22computerrequirements,9, 33,35convertingIDF files to ADF portableformat,107CORSIKA,94

particlecodes,94,146cosmicneutrinos,70crofieldindex, seeAIRESobjectlibrary.crofileinfo, seeAIRES objectlibrary.crofileversion, seeAIRESobjectlibrary.crogotorec, seeAIRES objectlibrary.croheaderinfo, seeAIRESobjectlibrary.croinputdata0, seeAIRESobjectlibrary.crooldata, seeAIRES objectlibrary.croreccount, seeAIRES objectlibrary.crorecfind, seeAIRES objectlibrary.crorecinfo, seeAIRES objectlibrary.crorecnumber, seeAIRES objectlibrary.crorecstrut, seeAIRES objectlibrary.crorewind, seeAIRES objectlibrary.crospcode, seeAIRES objectlibrary.crospmodinfo, seeAIRES objectlibrary.crospnames, seeAIRES objectlibrary.crossedobservinglevelskey, 91, 100,192crotaskid, seeAIRES objectlibrary.

depthof first interaction,76,78,79,85,141,199dielectricsuppression,v, 3, 4, 22,70,118,125dumpfileversion, seeAIRES objectlibrary.dumpfileversiono, seeAIRESobjectlibrary.dumpinputdata0, seeAIRESobjectlibrary.

Earth’scurvature,4, 9, 11,17,18,79,225Earth’smagneticfield, seegeomagneticfieldEHSA,seeextendedHillas splittingalgorithmenergy distributions,2, 4, 27,28,38,67,80,118,

140errormessages,46exotic primaries,seespecialprimaryparticlesexporteddatafiles,54,57,60,79,106,117,119,

137for singleshowers,119

extendedHillas splittingalgorithm,3, 4, 68,221externalpackages,v, 3, 5, 8, 20,23,64,65,68,79,

117,120,122,123,126,170

fault tolerantprocessing,8, 58,101file directories,seeAIRES file directoriesfirst showernumber, 85,121

INDEX 233

fitghf, seeAIRES objectlibrary.

Gaisser-Hillas function,79, 81,100,171,183,185fitting, 170inverseof, 184

gammarayconversionin thegeomagneticfield,222

GEANTparticlecodes,94,146

geographicazimuth,62,129,154geomagneticfield, 2, 4, 8, 11,19,40,64,117,

123,155,226fluctuations,65,123

getcrorecord, seeAIRES objectlibrary.getcrorectype, seeAIRESobjectlibrary.getglobal, seeAIRES objectlibrary.getinpint, seeAIRES objectlibrary.getinpreal, seeAIRES objectlibrary.getinpstring, seeAIRES objectlibrary.getinpswitch, seeAIRES objectlibrary.getlgtinit, seeAIRES objectlibrary.getlgtrecord, seeAIRES objectlibrary.ghfin, seeAIRES objectlibrary.ghfpars, seeAIRESobjectlibrary.ghfx, seeAIRES objectlibrary.globalvariables,50,51,96,117,133,175,222grandom, seeAIRESobjectlibrary.

hadroniccrosssections,4, 24,25,69,126low energy, 126,221

hadronicmodels,3, 5, 23,68,120,122,126Hillas, A. M., 2, 3, 23,28,68,217,218

IDF or idf, seeinternaldumpfileIDL, seeInputDirectiveLanguage.idlcheck, seeAIRESobjectlibrary.IGRF, seeInternationalGeomagneticReference

FieldInputDirectiveLanguage,v, 2, 8, 45,216,218,

225directives?, 48,123#, 50,51,80,115&, 50,115AddSite, 64,115, 134AddSpecialParticle, 71,72,75,

115, 124,129ADFile, 52,54,107,115AirAvgZ/A, 70,116AirRadLength, 70,116

AirZeff, 70,116Atmosphere, 116Brackets, 116, 218CheckOnly, 47,48,101,117CommentCharacter, 80,81,117Date, 65,117DelGlobal, 50,117, 218DielectricSuppression, 70,118DumpFile, 118ElectronCutEnergy, 52,118, 218ElectronRoughCut, 70,118, 218,223ELimsTables, 67,118EMtoHadronWFRatio, 66,119, 218End, 46,52,107,114,119Exit, 48,119ExportPerShower, 81,119ExportTables, 52,54,80,81,107,

119, 137ExtCollModel, 68,120ExtNucNucMFP, 69,120, 216FileDirectory, 60,121FirstShowerNumber, 75,85,121ForceInit, 59,121ForceLowEAnnihilation, 70,121,

217,218ForceLowEDecays, 70,122, 217,218ForceModelName, 69,122GammaCutEnergy, 52,122, 219GammaRoughCut, 70,122, 219,223GeomagneticField, 65,123GroundAltitude, 50,51,63,123GroundDepth (synonym ofGroundAltitude), 123

Help, 48,123Import, 50,51,124, 218InjectionAltitude, 63,124InjectionDepth (synonym ofInjectionAltitude), 124

Input, 47,48,60,114,124,124InputListing, 58,70,124InputPath, 60,115,124,124, 204LaTeX, 78,125LPMEffect, 70,125MaxCpuTimePerRun, 58,125MesonCutEnergy, 52,125, 219MFPHadronic, 69,126MFPThreshold, 69,126MinExtCollEnergy, 68,126, 216MinExtNucCollEnergy, 68,126, 216

234 INDEX

MuonBremsstrahlung, 70,127, 218MuonCutEnergy, 52,127, 219NuclCollisions, 69,127NuclCutEnergy, 52,127, 219ObservingLevels, 51,63,67,93,128OutputListing, 78,128PerShowerData, 67,80,119,128PhotoNuclear, 69,128PrimaryAzimAngle, 50,62,129PrimaryEnergy, 46,51,61,71,129,

218PrimaryParticle, 46,51,61,71,129PrimaryZenAngle, 50,51,62,130PrintTables, 52,54,79,130, 137Prompt, 48,130PropagatePrimary, 69,130RandomSeed, 67,131RecordObsLevels, 93,131Remark, 50,51,131ResamplingRatio, 89,92,132,132RLimsFile, 89,92,132RLimsTables, 67,132RunsPerProcess, 58,132SaveInFile, 53,90,92,93,132SaveNotInFile, 53,90,92,133SeparateShowers, 133SetGlobal, 50,51,133, 218SetTimeAtInjection, 70,133ShowersPerRun, 58,133Site, 64,115,123,134Skip, 50,51,134SpecialParticLog, 76,134StackInformation, 78,134Summary, 78,80,107,134TableIndex, 79,130,135TaskName, 46,51,80,107,135ThinningEnergy, 51,66,135ThinningWFactor, 66,135, 216TotalShowers, 46,51,59,75,135Trace, 47,48,101,136TSSFile, 83,136, 216x, 48,119

dynamic/staticdirectives,46,57,59,114format,46,114hiddendirectives,48,58,70,114physicalunits,48,49,222referencemanual,114

inputfile checking,46,101installingAIRES,9, 109,218

internaldumpfile, vi, 8, 45,57,59,60,67,68,77,103,106,131,188,221,224

accessing,96portableformat,54,57,60,77,107,115,224processingwith AIRES summaryprogram,

77InternationalGeomagneticReferenceField,4, 20,

64,117,123,217,221,226

knock-onelectrons,v, 3, 4, 22,23,218,221

lateraldistributions,2, 4, 27,28,30,38,67,132,139

LATEX formatfor summaryfiles,78,125loadumpfile, seeAIRES objectlibrary.log file, 57,60,76,134longitudinaldevelopment,2, 4, 27,28,30,36,63,

67,77,78,128,137depositedenergy, 142in energy, 36,52,138low energy particles,142

low energy particles,70annihilation,121decay, 122

LPM effect,v, 3, 4, 22,26,70,118,125,225,226

magneticazimuth,62,129meanfreepath,24

hadronic,25,69,126nucleus-nucleuscollisions,25,120,126

mixedcomposition,61,72MOCCA, 1, 2, 6, 16,22,23,94,223,225,227

particlecodes,94,146MOCCA SP, 3multipleprimaries,seespecialprimaryparticlesmuonbremsstrahlung,v, 3, 4, 22,70,127,217,

221muonicpair production,4, 70,127,215,217,221

Netlib, 3, 79,170acb�d�e, 78,141

nuclcode, seeAIRESobjectlibrary.nucldecode, seeAIRES objectlibrary.nucleus-nucleuscollisions,4, 68,120,126,220

olcoord, seeAIRESobjectlibrary.olcrossed, seeAIRES objectlibrary.olcrossedu, seeAIRES objectlibrary.olsavemarked, seeAIRES objectlibrary.olv2slant, seeAIRES objectlibrary.onlinehelp,48

INDEX 235

opencrofile, seeAIRES objectlibrary.outputdatatables,54,66,106,137,219,221,

224–226

pair production,v, 3, 4, 22,122particlecodes,20,94,95,146,155photoelectriceffect,v, 3, 4, 22photonuclearreactions,v, 3, 4, 23,129portabledumpfile, seeinternaldumpfile, portable

formatpositronannihilation,v, 3, 4, 22–24,118,217pre-showers,71primaryenergy spectrum,61,129process,definition,45

QGSJET, v, 3, 4, 23,25,54,68,102,111,120,122,126,216,220,222,223,226

randomnumbergenerator, 27,67,74,100,131,186,197,213,224

elementarywithoutseed,67,148raninit, seeAIRESobjectlibrary.recompilingsimulationprograms,112regetcrorecord, seeAIRESobjectlibrary.releasenotes,215resamplingalgorithm,86,90,132,222rewindingcompressedfiles,100,162run,definition,45

showeraxis-injectionpoint coordinatesystem,74,199,201,202,207

showermaximum,27,36,78,91SIBYLL, v, 3, 4, 23,25,68,94,120,122,126,

216,220,223,226,227particlecodes,94,146

singleshower tables,67,80,107slantatmosphericdepth,seeatmosphericdepth,

slantsp1stint, seeAIRESobjectlibrary.spaddnull, seeAIRES objectlibrary.spaddp0, seeAIRESobjectlibrary.spaddpn, seeAIRESobjectlibrary.specialprimaryparticles,v, 3–5,8, 61,70, 73,84,

88,90,100,115,129,131,133,134,144,163–165,199–211,222

logging,76speiend, seeAIRESobjectlibrary.speigetmodname, seeAIRESobjectlibrary.speigetpars, seeAIRES objectlibrary.speimv, seeAIRES objectlibrary.

speistart, seeAIRES objectlibrary.speitask, seeAIRESobjectlibrary.spinjpoint, seeAIRES objectlibrary.splittingalgorithm,23,86,217,218

extended,seeextendedHillas splittingalgorithm

spnshowers, seeAIRES objectlibrary.sprimname, seeAIRES objectlibrary.statisticalweightfactor, 29, 32,34,35,66,119,

135summaryfile, 8, 57,60,77,78

tasksummaryscriptfile, 8, 57,77,81,82,136,216,220

task,definition,45tasks,processesandruns,45,58,103thinning,v, 2, 4, 8–10,27,30–33,38,51,66,85,

110,119,135,154,221AIRES extendedalgorithm,29, 34,35,40,

66,221,223Hillas algorithm,9, 28, 29–31,34,40

thisairesversion, seeAIRESobjectlibrary.thresholdenergies,23,26,52,53,68–70,86,118,

122,125–127timedistributions,27,39,141TSSor tss,seetasksummaryscriptfile

unweighteddistributions,28,137,139,140urandom, seeAIRESobjectlibrary.urandomt, seeAIRESobjectlibrary.US standardatmosphere,13,14,17,116

verticalatmosphericdepth,seeatmosphericdepth,vertical

f`b�dEe, 27,78,128,141

xslant, seeAIRES objectlibrary.

236 NOTES

NOTES 237

238 NOTES

aires user's manual and reference guide

Documents