Quick User Guide for GYOTO
Contents
1. http www boost org www boost org doc libs 1 55 0 1ibs numeric odeint doc html index html e Legacy integrator does not support the Abslol nor the Rellol parameters SThe Legacy integrator take the DeltaMin DeltaMax and DeltaMaxOverR parameters in the Metric section 10 DeltaMaxOverR this is h Onax T such that at any position the integration step may not be larger than h x r where r is the current distance to the centre of the coordinate system defaults to 1 Maxiter maximum number of integration steps per photon Adaptive or NonAdaptive whether or not to use an adaptive step Delta integration step initial in case it is adaptive Not very important but should be commensurable with the distance to the Screen i e don t use Delta 107 if the screen is at 105 geometrical units Delta can be specified in any distance like or time like unit MinimumTime stop integration when the photon travels back to this date Defaults to the earliest possible date Can be specified in any time like or distance like unit 4 1 The Boost integrators If GYOTO was compiled with a C 11 capable compiler and with the Boost library ver sion 1 53 or above then the following integrators are available e runge kutta cash karp54 e runge kutta fehlberg 8 e runge kutta dopris e runge kutta cash karp54 classic alternate implementation of runge kutta cash karp54 Those integrators are implemented in the World2. i e units with c and G put to 1 The Time field gives the time of observation The FieldOfView is given in radians The screen s Resolution is the number of screen pixels in each direction Screen Position 1000 100 1 22 0 lt Position gt Time unit geometrical time 1000 Time FieldOfView 0 314159265358979323846264338327950288419716 FieldOfView Resolution 32 Resolution Screen The screen is now defined The following line describes the target object that will be ray traced Astrobj kind PageThorneDisk Here the target object is very simple and requires no specifications The Scenery is now fully defined and the field can be closed lt Scenery gt This is the end of the XML input file Figure 1 Image of a Page Thorne thin accretion disk around a Schwarzschild black hole with a 32 x 32 pixels screen 2 1 2 Calling gyoto We will now use the gyoto command line tools to ray trace the scenery described in this XML file The command line options are documented in the usual UNIX style manpage man gyoto Once the XML input file is ready the call to gyoto is done according to the following line gyoto input xml output fits where input xml is the above mentioned XML file and output fits is the name of the FITS that will contain the result of the computation The before the fits file allows to overwrite a pre existing file If you remove it an error wil
3. Quantities gt Spectrum lt Quantities gt When this command is used the output FITS file will contain a cube of images each image corresponding to one observed frequency Computing the spectrum is now straightforward Remembering that the flux is linked to the intensity by dF Vine doa cosP dQ 1 where Q is the solid angle under which the emitting element is seen and 6 is the angle between the normal to the observer s screen and the direction of incidence the flux is given by ing Vi i COS O pixel OL dii 2 pixels where Zp pixel S the specific intensity reaching the given pixel 9pixe is the angle between the normal to the screen and the direction of incidence corresponding to this pixel and dQpixe is the element of solid angle introduced above 16 This quantity Fp can thus be very simply computed from the cube of specific in tensities computed by GYOTO Examples of spectra computed by GYOTO can be found in e g 2012 Section 3 1 contains example code to compute a spectrum di rectly using the provided Yorick interface See also yorick check polish doughnut i which does just that as part of the routine test suite of GYOTO 7 GYOTO in numerical metrics A specificity of GYOTO is its ability to ray trace in non Kerr metrics numerically computed in the framework of the 3 1 formalism of general relativity Gourgoulhon 2012 e g by means of the open source LORENE library developed by the Numerical Rel
4. Quick User Guide for GYOTO Updated June 20 2014 Introduction Scope of this Guide This Guide aims at giving a general presentation of the General relativitY Orbit Tracer of Observatoire de Paris GYOTO pronounced dzioto as for the Italian trecento painter Giotto di Bondone This text is not a lecture on ray tracing techniques and is only devoted to presenting the code so that it can be quickly handled by any user Readers interested in the physics behind GYOTO are referred to and references therein The aim of this Guide is also to present the code in sufficient details so that people interested to develop their own version of GYOTO can do it easily GYOTO is an open source C code with a Yorick plug in that computes null and time like geodesics in the Kerr metric as well as in any metric computed within the framework of the 3 1 formalism of general relativity This code allows to compute mainly images and spectra of astrophysical sources emitting electromagnetic radiation in the vicinity of compact objects e g accretion disks or nearby stars As GYOTO is continually evolving this guide will hopefully be regularly updated to present the new functionalities added to the code However this guide does not constitute a full reference The reference manual is built from the C header files using doxygen into the doc html directory of the source tree It is also available online rebuilt every night at http gyoto obspm fr Th
5. T Gourgoulhon E and Perrin G 2011 GYOTO a new general relativistic ray tracing code Classical and Quantum Gravity 28 22 225011 22
6. ativity group at Observatoire de Paris LUTH For the time being only a simple example of numerical metric is implemented in the public version of GYOTO the metric of a relativistic rotating star The file doc examples example movingstar rotstar3 1 xml allows to ray trace a basic GYOTO moving Star in this metric The file resu d specified in the XML file is the out put of a LORENE computation for the metric of a rotating relativistic star by the LORENE nrotstar code The basic functions developed in 1ib RotStar3 1 C are similar to their Kerr coun terparts but here the metric is expressed in terms of the 3 1 quantities lapse shift 3 metric extrinsic curvature The equation of geodesics expressed in the 3 1 formalism is given in Vincent et al and implemented in 1ib RotStar3_1 C However it is possible to choose in the XML file whether the integration will be performed by using this 3 1 equation of geodesics or by using the most general 4D equation of geodesics see Vincent et al 2011 for a comparison of the two methods 8 Extending GYOTO This section is currently under construction GYOTO can be extended easily by adding new Metric Astrobj and Spectrum classes Such classes can be bundled in GYOTO plug ins The main GYOTO code base already contain two plug ins stdplug which contain all the standard analytical metrics and all the standard astrophysical object and lorene which contains the numerical LORENE based metrics In add
7. ccess to your objects from the Yorick interface you will need to provide a Yorick plug in around your GYOTO plug in Look at the content ofthe yorick stdplug directory For new official GYOTO objects in the standard plug in it is fairly easy to provide an interface directly inside our Yorick plug in 8 6 Quality assurance It is customary to provide a test suite for every new class in GYOTO This normally includes an example file in doc examples which is ray traced in the check target of bin Makefile am Usually we also provide a new Yorick test file called yorick check myclass i which is called from yorick check i This is a good idea to do so even if you don t intend on using the Yorick plug in at least you can use this interpreted interface to perform unit tests on your code in a more fine grained manner than a full featured ray traced image 21 References Gourgoulhon E 2012 9 1 Formalism in General Relativity Springer Heidelberg Ger many Page D N and Thorne K S 1974 Disk Accretion onto a Black Hole Time Averaged Structure of Accretion Disk ApJ 191 499 506 Straub O Vincent F H Abramowicz M A Gourgoulhon E and Paumard T 2012 Modelling the black hole silhouette in Sagittarius A with ion tori A amp A 543 A83 Vincent F H Gourgoulhon E and Novak J 2012 3 1 geodesic equation and images in numerical spacetimes Classical and Quantum Gravity 29 24 245005 Vincent F H Paumard
8. choice seems to be lt Scenery gt 12 lt Integrator gt runge kutta fehlberg78 lt Integrator gt lt AbsTol gt 1e 19 lt AbsTol gt lt RelTol gt 1e 19 lt RelTol gt lt Scenery gt If computation time is more critical than accuracy the other Boost integrators are also good choices The Yorick code that was used to generate Fig 3 is provided in the GYOTO source code as yorick compare integrators i You can run it from the top directory of the built source tree as yorick yorick i yorick compare integrators i 5 GYOTO architecture 9 1 GYOTO base classes GYOTO is basically organised around 8 base classes see Fig 4 The Metric class it describes the metric of the space time Kerr in Boyer Lindquist coordinates Kerr in Kerr Schild coordinates metric of a relativistic rotating star in 3 1 formalism The Astrobj class it describes the astrophysical target object that must ray traced e g a thin accretion disk a thick 3D disk a star The Spectrum class it describes the emitted spectrum of the Astrobj TheWorldline class it gives the evolving coordinates of a time like or null geodesic The Star class is a sub class of Worldline as for the time being a star in GYOTO is only described by the time like geodesic of its centre with a given fixed radius The WorldlineIntegState class it describes the integration of the Worldline in the given Metric The Screen class it describes the observer s scre
9. e s 5 nm 1 mr L Error on deflection angle uas Hoj po po po pj o 0 1 to t die r je i po or 0 2 1 1 l 10 10 10715 10 20 10 10 10715 10 20 104 1072 1079 1072 104 AbsTol and RelTol or DeltaMaxOverR5 1e8 AbsTol and RelTol or DeltaMaxOverR5 1e8 Error on deflection angle uas Figure 3 Comparison of the integrators when measuring a deflection angle see text Left error on deflection angle vs tuning parameter centre computing time vs tun ing parameter right computing time vs error on deflection angle Colours denote the integrator red Legacy solid specific KerrBL implementation dash dotted generic im plementation black runge kutta fehlberg78 blue runge kutta karp54 magenta runge kutta dopri5 4 3 Integrator comparison It is advisable to try the various integrators in your context and to play with the tuning parameters As a rule of thumbs if you need to change DeltaMin DeltaMax Delta MaxOverR or Maxiter it probably means that you should change for a higher order integrator The highest order integrator is currently runge kutta fehlberg78 and is the default As an example we have compared all the integrators for a simple situation the Metric is a Schwarzschild black hole of 4 x 10 Mo the Screen is at 8 kpc a single light ray is launched 50 uas from the centre we integrate the light ray back in time during twice the travel time to the origi
10. e reader is strongly encouraged to give feedback on this Manual report typos ask questions or suggest improvements by sending an email to frederic vincentQobspm fr Contents 1 Installing GYOTO 21 Using the gyoto command line tool s 2 1 1 XML input file sa sales 482 a uja om E Edi o anla a E 21 2 CAGE p pobo a 3454 Be a ka ando EST SE os 2 ls FITS ontput flej s ers sss e Sg ESP 6 ek PLS a an 883 2 2 The gyotoy interface 4 pas Oe SB a sea aj E Es NE ES 3 Beyond the basics scripting GYOTO 3 1 Using the Yorick plug in sas sa buka E eee wee ed wee eS 3 2 Interfacing directly to the GYOTO library 9 9 73 eee Ae ee a SNS 11 a hers aes ee TTT 11 aot ba eee hee A E 12 NNOA BD Oo QO 5 GYOTO architecture 13 5 1 GYOTO base classes oso 13 5 2 A typical GYOTO computation 222642 kus gu kaas ika asi kus 15 6 7 8 Computing an image or a spectrum in the Kerr metric with GYOTO ee a E E a de sus vs ree eo ee ee hn ee ge ee a a ce ea Lh LE Kako eR l p a oa GYOTO in numerical metrics Extending GYOTO sig gj Ua akoj SU Be EO kavo BS Re MISS 8 2 Adding a new metric Metric 3 a0 4 su a0 eda sek asd awe ME as 8 3 Adding a new spectrum Spectrum s s ss ss 4 sss sa sa 8 4 Adding a new astrophysical target object Astrobj kea bie eee ee am Ree A eS Sa es Pow eee se eae oe eee DR eee 15 15 16 16 17 1 I
11. en its resolution its position in space time its field of view The Scenery class it describes the ray tracing scene It is made of a Metric a Screen an Astrobj and the quantities that must be computed an image a spectrum The Factory class it allows to translate the XML input file into C objects Fig 4 presents the main GYOTO classes and their hierarchy 13 Gyoto Scenery Gyoto Metric KerrBL Gyoto Metric KerrKS Gyoto Metric RotStar3 1 Gyoto Metric yoto Astrobj Complex Gyoto Astrobj Torus yoto Astrobj Standard yoto Astrobj Star yoto Astrobj UniformSphere yoto Astrobj FixedStar Gyoto Astrobj PageThorneDisk yoto Astrobj PatternDisk yoto Astrobj PatternDiskBB Gyoto Astrobj ThinDisk Gyoto Astrobj Gyoto Astrobj DynamicalDisk Gyoto Astrobj ThinDiskPL yoto Astrobj Disk3D gt r Gyoto Astrobj Disk3D BB Gyoto Spectrum BlackBody yoto Spectrum Generic Gyoto Spectrum PowerLaw Gyoto Astrobj Star yoto Worldline Gyoto Photon Gyoto WorldlinelntegState Gyoto Screen Gyoto Factory Figure 4 Hierarchy of GYOTO C main classes 14 5 2 A typical GYOTO computation Let us now describe the main interactions of these various classes during the computation of one given photon ray traced in the Kerr metric in Boyer Lindquist coo
12. from the XML file For each XML entity found in the Metric section in the form lt ParName unit unit name ParValueString ParName the method Metric Generic setParameters will call setParameter ParName ParValueString unit name virtual void setParameter std string std string std string setParameter should interpret the parameters specific to this class and pass whatever remains to the Generic implementation setParameter has a counterpart fillElement which is mostly used by the Yorick plug in Sect to dump an in memory object instance to text format this is what allows gyotoy Sect to write its parameters to disk This method must be compiled only if XML input output is compiled in 19 ifdef GYOTO USE XERCES virtual void fillElement FactoryMessenger fmp endif The Minkowski implementation goes on with an alternate implementation of gmunu and christoffel For the purpose of this documentation we will skip these additional examples and close the header file here F endif For more details see the GYOTO reference manual in doc htm1 or at http gyoto There are a few other methods that are worthwhile reimplementing such as circularVelocity which allows getting accurate beaming effects for thin disks and tori Naturally circularVelocity can only be implemented if circular orbits physically exist in this metric else the Keplerian approximation is readily provided by the generic im
13. function that asks the Astrobj whether the integrated photon has reached it or not When the photon has reached the target this Astrobj Impact function calls the Astrobj processHitQuantities function that updates the data depending on the user s specifications 6 Computing an image or a spectrum in the Kerr met ric with GYOTO 6 1 The Screen The observer s Screen is made of N x N pixels and has a field of view of f radians The field of view is defined as the maximum angle between the normal to the screen and the most tangential incoming geodesic Keep in mind that the screen is point like the different pixels are all at the same position the one and only screen position defined in the XML file but the various pixels define various angles on the observer s sky For instance if f 7 2 which gives a view of the complete half space in front of the screen the geodesic that hits the screen on the central pixel i N 2 j N 2 comes from the direction normal to the screen whereas the geodesic that hits the screen on the i N j N 2 pixel comes from a direction tangential to the screen Each pixel of the screen thus covers a small solid angle on the observer s sky This elementary solid angle is equal to the solid angle subtended by a cone of opening angle f 15 divided by the number of pixels Npixe 27 1 cos f N assuming the field of view is small enough 6 2 Computing an image The quantity that is carried alo
14. i metric actually provided in the standard plug in in a plugin called myplugin you would write a C file whose name is not relevant but assume MyPlugin C with this content include GyotoMinkowski h using namespace Gyoto extern C void __GyotomypluginInit 1 Metric Register Minkowski amp Metric Subcontractor lt Metric Minkowski gt Likewise you could register more metrics astrophysical objects and spectra Other examples can be seen in the lib StdPlug C and lib LorenePlug C files When building your plug in make sure MyPlugin C ends up compiled with lib Minkowski C in this example into a single shared library called libgyoto myplugin so assuming you work under Linux and drop this file somewhere where the linker will find it at run time The following places are good choices e where ever libgyoto stdplug so gets installed e usr local lib e usr lib GYOTO ships a pkg config file gyoto pc which stores contains useful build time in formation such as the install prefix and the plug in suffix This file gets installed in the standard location by default usr local 1ib pkgconfig gyoto pc 8 22 Adding a new metric Metric The simplest example for a Metric object is certainly the Minkowski class Let s go through the header file that defines its interface expunged from all this useless documen tation we trust the reader to go see the corresponding C file Avoid multiple and recursive incl
15. ition we maintain our own private plug in which contains experimental or yet unpublished Astrobj and Metric classes When we make a publication based on these classes we move them from our private plug in to the relevant public plug in We kindly request that you follow the same philosophy whenever you write a new class and make a publication out of it please publish the code as free software either on your own servers or by letting us include it in GYOTO As soon as you write your own objects you will dependent on the stability of the GYOTO application programming interface which is subject to frequent changes It will help us to help you maintain your code if you inform us of such development gyoto sympa obspm fr http www lorene obspm fr 17 8 1 Writing a plug in A plug in is merely a shared library which contains the object code for your new objects plus a special initialisation function It is loaded into memory using dlopen by the function Gyoto loadPlugin char const const name int nofail implemented in lib Register C The name argument will be used twice e the shared library file must be called libgyoto name suffix suffix is usually so under Linux dylib under Mac OS e the init function for your plug in must be called Gyotoname Init The role of the init function is to register subcontractors for your object classes so that they can be found by name For instance assuming you want to bundle the Minkowsk
16. l occur if the fits file already exists The line above asks GYOTO to integrate a null geodesic from each pixel of the screen backward in time towards the astrophysical object You can accelerate computations by using several cores on a computer using the nthreads NCORES option NCORES is the number of threads that GYOTO will use The optimal value is usually the number of hardware CPU cores on the machine This option can also be specified in the input file using the NThreads entity This facility does not work for LORENE based metrics see Sect 7 Another cheap way of parallelising the computation is to call several gyoto instances running on different CPUs or even on different machines each instance computing only a portion of the image This sort of basic parrallelisation is naturally supported by all the GYOTO metrics You can ask GYOTO to compute only a fraction of the screen s pixels by running gyoto imin IMIN imax IMAX jmin JMIN jmax JMAX input xml output fits where IMIN IMAX JMIN JMAX are the extremal indices of the pixels that will be computed For instance to compute only the geodesic that hits the central pixel of a 32 x 32 screen type gyoto imin 16 imax 16 jmin 16 jmax 16 input xml output fits How to recombine the several output files into a single FITS file is left as an exercise to the reader It is easily done using any scientific interpreted language such as Yorick or Python Severa
17. l other parameters can be overridden on the command line This includes the position of the Screen and the observing time time TIME which is quite useful to produce a movie 2 1 3 FITS output file Once the computation is performed the output fits file is created You can visualise it by using the ds9 software http hea www harvard edu RD ds9 site Home htm1 and simply running ds9 ouput fits For instance if you use the example page thorne disk BL xml as is you will obtain Fig 2 22 The gyotoy interface The second most basic tool provided by GYOTO is gyotoy Fig 2 This is a graphical user interface to visualize a single geodesic See the README and INSTALL files for the prerequisites Once the installation is complete your launch gyotoy as gyotoy or from the yorick sub directory of the built source tree yorick i gyotoy i followed on the Yorick prompt by gt gyotoy You can select a KerrBL metric and set the spin or any other metric defined in an XML file As of writing gyotoy assumes that the coordinate system is spherical like It should work in Cartesian coordinates as well but the labels will be odd It is possible to select Which kind of geodesic to compute time like or light like using the Star or Photon radio buttons the initial position and 3 velocity of the particle and the projection a k a the position of the observer The bottom tool bar allows selecting a few numerical parame
18. line object This has the advantage that when ray tracing the image of a moving star Star class the star can use a different integrator than the photons These integrators support all of the parameters described above 4 2 The Legacy integrator The Legacy integrator is a home brewed 4 order adaptive step Runge Kutta integra tor It is always available independent of any compile time options It does not support AbsTol nor RelTol and takes DeltaMin DeltaMax and DeltaMaxOver in the Metric section not in the Scenery or Astrobj section It is not possible to use different tuning parameters for the Star and the Photons if both use the Legacy integrator The Legacy integrator is implemented in the Metric object and may be re implemented by specific Metric kinds Most notably the KerrBL metric reimplements it this specific implementation takes advantage of the specific constants of motion When a metric reimplements the Legacy integrator it is possible to choose which implementation to choose by specifying either lt GenericIntegrator gt or SpecificIntegrator in the Metric section The KerrBL specific implementation of the Legacy integrator accepts one additional tuning parameter DiffTol which defaults to 1072 and empirically seems to have very little actual impact on the behaviour of the integrator 11 o o o a 5 0 Li i Computing time s 5 TT LL SS Computing tim
19. ment variableGYOTO PLUGINS with a command such as How to do it depends on your shell and is outside the scope of this manual 20 export GYOTO PLUGINS stdplug myplugin Alternatively a list of plug ins can be specified on the command line when using the gyoto tool gyoto plugins stdplug myplugin A plug in can also be specified in the input XML file for each section Metric kind KerrBL plugin stdplug gt Finally the Yorick interface Sect 3 1 has a function to explicitly load a GYOTO plug in at run time gyoto loadPlugin myplugin Once the plug in is loaded your new object kinds should be registered that s the purpose of the init function To check that your objects are correctly register you can use the debug option of the gyoto tool or the gyoto listRegister function of the Yorick interface You can use then use your classes directly in an XML file using the name you provided to the Register function in the init function of the plug in Metric kind Minkowski plugin myplugin gt The Yorick interface can load any object from an XML description an can also initialise any object from its name gyoto loadPlugin myplugin metric gyoto Metric Minkowski If your object supports any options using the setParameter method these options can also be set from within Yorick gt metric setparameter ParName ParValueString unit unit string If your want finer a
20. midpoints unit Hz gt plg spectrum freq gt xytitles Frequency Hz Spectrum mJy 3 2 Interfacing directly to the GYOTO library The core functionality is provided as a C shared library which is used both by the gyoto command line tool and the Yorick plug in You can of course interface directly to this library The reference is generated from the source code using doxygen in the directory doc html The application binary interface ABI is likely to change with every commit We try to maintain a certain stability in the application programming interface API but the effort we put into this stability is function of the needs of our users If you start depending on the GYOTO library please contact us gyoto sympa obspm fr we will try harder to facilitate your work or at least warn you when there is a significant API change 4 Choosing the right integrator Numerical ray tracing can be very much time consuming In order to control the nu merical errors in your application it is wise to experiment with the numerical tuning parameters GYOTO provides several distinct integrators depending on compile time op tions e the Legacy integrator the first to have been introduced e Boost integrators from the odeint llibrary In GYOTO they are called runge kutta see below The integrator and its numerical tuning parameters can be specified in either of these three XML sections Scenery to specify the integra
21. n of the coordinate centre and compute the deflection angle We do that for each integrator and a set of numerical tuning parameters For the Legacy integrator we try both the generic integrator and the specific KerrBL implementation and use DeltaMaxOverR as tuning parameter For the Boost integrators we use AbsTol and RelTol as tuning parameters they are kept equal to each other We then compare the result for two values of the tuning parameter and measure the computing time required for each realisation For each integrator there exists an optimum value or the tuning parameter for which the estimated uncertainty in deflection angle is minimal Fig 3 left panel As long as the tuning parameter is larger than or equal to this optimum computation time varies very little central panel However when the tuning parameter becomes too small numerical error and computation time explode right panel The two low order Boost integrators are the fastest the two Legacy integrators are the slowest The default runge kutta fehlberg78 has intermediate performance but seems to yield the smallest error and to be less sensitive on the exact value of the tuning parameter close to its optimum All the integrators except the generic implementation of the Legacy integrator agree to within 2 as on the deflection angle which is of order 33A The relative uncertainty is therefore of order 107 In conclusion for this specific use case the best
22. ng the geodesics computed by GYOTO in most cases is the specific intensity 1 erg em s ster Hz7 An image is then defined as a map of specific intensity each pixel of the screen contains one value of 1 that can then be plotted It is important to keep in mind that such an image is not physically equivalent to a real image that would be obtained with a telescope a real image is a map of specific fluxes values and a specific flux is the sum of the specific intensity on some solid angle An example of image computation has already been given in Section 63 Computing a spectrum To compute a spectrum the Screen field of the XML file should contain information about the observed frequency range For a real telescope this means adding a spectrometer The additional command in the XML file is thus Spectrometer kind freqlog nsamples 20 gt 5 25 lt Spectrometer gt This line means that that 20 values of observed frequencies will be considered evenly spaced logarithmically between 10 and 10 Hz It is possible to choose frequencies linearly evenly spaced by using freq instead of freqlog It is also possible to use wave lengths instead of frequencies see GyotoScreen h for more information Moreover the XML file should explicitly state that the quantity of interest is no longer a simple image but a spectrum This is allowed by the following command that should be added for instance before the end of Scenery field lt
23. nstalling GYOTO GYOTO is freely available at the URL http gyoto obspm fr This URL hosts the online manual of GYOTO with installation instructions and brief descriptions of the code architecture GYOTO is version controlled with the git software that you should install on your machine Before uploading the code be sure that the xerces c3 or xercesc3 depending on the architecture and cfitsio libraries are installed on your system GYOTO won t compile without these It is also better but not required to install the udunits2 library Once this is done just type on a command line git clone git github com gyoto Gyoto git which will create a Gyoto repository It contains directories bin lib include doc yorick containing respectively the core code and executable the C source files the h headers the documentation and Yorick plug in related code In the Gyoto repository use the standard configure make sudo make install commands to build the code In case of problems have a look at the INSTALL file that gives important complemen tary informations on how to install GYOTO 2 Basic usage 2 1 Using the gyoto command line tool The most basic way of using GYOTO is through the gyoto command line tools It relies on two kinds of files an XML file containing the inputs and a FITS file containing the outputs 2 1 1 XML input file You can find examples of XML input files in doc examples Let us consider the compu tati
24. on of the image of a standard Page Thorne accretion disk in Boyer Lindquist coordi nates described in example page thorne disk BL xml If you are not familiar with XML language just remember that an XML file is made of several fields beginning with the lt Field Name gt and ending with lt Field Name gt One field can have sub fields defined with the same symbols For instance in example page thorne disk BL xml there is one global field Scenery describing the scenery that will be ray traced with a few sub fields Metric describing the metric used for the computation here the Kerr metric in Boyer Lindquist coordinates Screen describing the observer s screen properties finally Astrobj describing the astrophysical object that will be ray traced here a Page Thorne accretion disk All the parameters in this input file can be changed to specify a new scenery Let us present in details the example page thorne disk BL xml file lt xml version 1 0 encoding UTF 8 standalone no Scenery The following lines specify the metric it is the Kerr metric expressed in Boyer Lindquist coordinates with spin 0 so the Schwarzschild metric here Metric kind KerrBL gt lt Spin gt 0 lt Spin gt lt Metric gt The metric is now defined let us describe the observer s screen The Position field gives the screen s 4 position in Boyer Lindquist coordinates t r 0 p angles in radians time and radius in geometrical units
25. plementation Some other low level methods can be reimplemented but it is not necessarily a good idea Once you have implemented the new Metric just make sure it is compiled into your plug in and initialised in the initialisation function Sect 8 1 For official GYOTO code that does not depend on LORENE this is done by adding your C file to libgyoto stdplug la SOURCES in lib Makefile am and running autoreconf followed by configure and adding one line in __GyotostdplugInit in lib StdPlug C 8 3 Adding a new spectrum Spectrum Adding a new spectrum kind is almost the same as adding a metric 8 4 Adding a new astrophysical target object Astrobj Adding a new astronomical object kind is almost the same as adding a metric However astronomical objects are more complex than metrics they can have abundant hair In stead of inheriting directly from the most generic base class Gyoto Astrobj Generic you will save yourself a lot of effort if you are able to derive from one of the higher level bases Astrobj ThinDisk a geometrically thin disk e g PageThorneDisk PatternDisk Astrobj UniformSphere a uniform sphere e g Star FixedStar Astrobj Standard any object whose boundary can be defined as an iso surface of some function of the coordinates such as a sphere or a torus e g UniformSphere Torus 8 5 Using your new plug in There are several ways to instruct GYOTO to load your plug in You can set the environ
26. rdinates towards for instance a PageThorneDisk i e a geometrically thin optically thick disk following 1974 All directories used in the following are located in GYOTO home directory GYOTO main program is located in bin gyoto C This program first interprets the command line given by the user It creates a new Factory object initialised by means of the XML input file that will itself create see lib Factory C the Scenery Screen and Astrobj objects The output quantities the user is interested in image spectrum will be stored during the computation in the data object of type Astrobj Properties The Scenery object is then used to perform the ray tracing by calling its rayTrace function All the functions that begin with fits allow to store the final output quantities in FITS format The function Scenery rayTrace calls Photon hit that forms the core of GYOTO Photon hit integrates the null geodesic from the observer s screen back ward in time until the target object is reached there are other stop conditions of course see lib Photon C Photon hit is basically made of a loop that calls the function WorldlineIntegState nextStep until a stop condition is reached WorldlineIntegState nextStep itself calls the correct adaptive fourth order Runge Kutta integrator RK4 depending on the metric used Here the metric being KerrBL the RK4 used is KerrBL myrk4 adaptive Moreover the Photon hit also calls the Astrobj Impact
27. ters such as whether or not to use an adaptive step Menus allow saving or opening the parameters as an XML file exporting the geodesic as a text file and saving the view as an image file in various formats The view can be zoomed and panned by clicking in the plot area dhmunro github io yorick doc https www python org Gyotoy Fichier Affichage Aide System 1 0 611434 0 822082 Particle type Star Photon Metric parameters Type KerrBL Spin param 0 99500000000000000 zu Fi Mass 4000000 00000000000000000 Initial conditions 10 79100000000000037 Bo 1 57079632679489656 qo 0 00000000000000000 to 0 00000000000000000 dr dt 0 00000000000000000 E iiaj 10 d8 dt 0 00000000000000000 rial a g oa el lala eat 10 A ul 5 dy dt 0 01666400000000000 5 PALN 180 00000000000000000 Inclination 120 00000000000000000 Phase 0 00000000000000000 papado Distance 8 00000000000000000 Integration parameters t 0 00000000000000000 SNR Yorick command Figure 2 The gyotoy graphical user interface 3 Beyond the basics scripting GYOTO We have seen the two most basic ways of using GYOTO computing a single frame using the gyoto command line tool and exploring a single geodesic using the gyotoy interface There is much more that GYOTO can be used for computing spectra performing model fitting computing movies evaluating lensing effects etc 3 1 Using the Yorick pl
28. tor and parameters used during ray tracing by the indi vidual photons Photon if the XML file describes a single photon the Yorick plug in and the gyotoy tool can make use of such an XML file Astrobj ifit is a Star for specifying the integrator and parameters used to compute the orbit of this star The full set of tuning parameters that may be supported by the Scenery section is lt Scenery gt Integrator runge kutta fehlberg78 lt Integrator gt lt Abstol gt 1e 6 Abstol RelTol 1e 6 RelTol DeltaMax 1 79769e 308 DeltaMax DeltaMin 2 22507e 308 DeltaMin DeltaMaxOverR 1 79769e 308 DeltaMaxOverR Maxiter 100000 Maxiter Adaptive Delta unit geometrical gt 1 Delta MinimumTime unit geometrical time 1 7e308 MinimumTime Scenery Integrator the integrator to use one of the runge_kutta_ or Legacy default if compiled in runge_kutta_fehlberg78 AbsTol gt absolute tolerance for adapting the integration step see http www boost org doc libs 1_55_0 libs numeric odeint doc html boost_numeric_odeint odeint_in_detail generation_functions html RelTol relative tolerance for adapting the integration step idem DeltaMax the absolute maximum value for the integration step defaults to the largest possible non infinite value DeltaMin the absolute minimum value defaults to the smallest possible strictly pos itive value
29. ug in Yorick is a fairly easy to learn interpreted computer language We provide a Yorick plug in which exposes the GYOTO functionalities to this language This plug in is self documented at the Yorick prompt try gt include gyoto i gt help gyoto A lot of the GYOTO test suite is written in Yorick which provides many example code in the various i files in the yorick directory of the GYOTO source tree Another example is provided by the gyotoy graphical interface Sect 2 2 For Yorick basics see e https github com dhmunro yorick e http dhmunro github io yorick doc e http yorick sourceforge net 5 na e http www maumae net yorick doc index php As a very minimalist example here is how to ray trace an XML scenery into a FITS file in Yorick rlwrap yorick This launches Yorick within the line editing facility rlwrap provided separately Then from the Yorick prompt include gyoto i restore gyoto sc Scenery input xml data sc Intensity fits write output fits data VM VI VI MV or in two lines gt include gyoto i gt fits write output fits gyoto Scenery input xml Intensity Likewise to integrate the spectrum over the field of view gt include gyoto i gt restore gyoto gt sc Scenery input xml gt data sc Spectrum mJy pix 2 gt spectrum data sum sum gt freq sc screen spectro
30. usion of header files ifndef __GyotoMinkowski_H_ define __GyotoMinkowski_H_ Minkowski is a metric include the Metric base class header file 18 include GyotoMetric h Declare that our new class goes into the Gyoto Metric namespace namespace Gyoto namespace Metric class Minkowski Declare that Minkowski inherits from the base class class Gyoto Metric Minkowski public Gyoto Metric Generic Each class must be friend with the corresponding SmartPointer class friend class Gyoto SmartPointer lt Gyoto Metric Minkowski gt Minkowski has no private data else we would put it here private Every class needs a constructor which will at least populate the kind_ attribute of the parent class and the kind of coordinate system Cartesian like or spherical like public Minkowski The cloner is important and easy to implement It must provide a deep copy of an object instance It is used in the multi threading case to make sure two threads don t tip on each other s toes and in the Yorick plug in Sect when you want to make a copy of an object rather than reference the same object virtual Minkowski clone const Then come the two most important methods which actually define the mathematical metric void gmunu double g 4 4 const double x const int christoffel double dst 4 4 4 const double x const The setParameter method is the one that interprets options
Download Pdf Manuals
Related Search