GYOTO(1)

📦
version 2.0.2 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💫 GYOTO — the General relativitY Orbit Tracer of Observatoire de Paris 💫

okay bestie, sit down, hydrate, because we're about to talk about literally bending light around black holes and I need you focused 💖

This is the manual for gyoto, section 1 of the User Manuals. Yes, that's the whole header. It's giving minimalist. We move on.

✨ NAME ✨

gyoto — the General relativitY Orbit Tracer of Observatoire de Paris. That's the whole name, and honestly? Iconic. The acronym is doing gymnastics and it ate. 🩰

🌈 SYNOPSIS 🌈

okay so here's the tea, this is how you actually invoke her:

gyoto [--silent|--quiet|--verbose[=N]|--debug]
      [--no-sigfpe]
      [--help[=class]] [--version] [--list]
      [--ispec=i0:i1:di] [--jspec=j0:j1:dj]
      ([--imin=i0] [--imax=i1] [--di=di])
      ([--jmin=j0] [--jmax=j1] [--dj=dj])
      [--time=tobs] [--tmin=tmin]
      [--fov=angle] [--resolution=npix] [--distance=dist]
      [--paln=Omega] [--inclination=i] [--argument=theta]
      [--nthreads=nth] [--nprocesses=nworkers]
      [--plugins=pluglist]
      [--impact-coords[=fname.fits]]
      [--unit[=unit]]
      [--parameter=Path::Name[=value]]
      [--xmlwrite=output.xml]
      [--] input.xml output.fits

and then, because one form wasn't enough, she also has a whole other mode:

gyoto mk-video [options]

that's right, she does movies too. multi-talented. main character energy, no cap. 🎬

💅 DESCRIPTION 💅

okay so Gyoto is a whole framework for computing geodesics in curved space-times. Which, in bestie terms, means it traces the paths that light and particles take when space itself is all warped and weird. 🌀

The gyoto utility program uses that framework to compute images of astronomical objects in the vicinity of compact objects (e.g. black-holes, the celebrities of the cosmos). And here's the wild part — those images get distorted by strong gravitational lensing. So you're not just looking at the thing, you're looking at the thing through the warped fabric of spacetime. it's giving funhouse mirror but make it astrophysics. 🪞✨

🦋 Form one: make me a picture 🦋

In the first form, gyoto takes a scenery description in XML format (input.xml), computes this scenery using relativistic ray-tracing, and saves the result in FITS format.

so: XML in, FITS out. clean. efficient. we love a pipeline. 🫶

🎀 Form two: make me a movie 🎀

In the second form, gyoto produces a movie. 🎥

For the deets, hit up gyoto mk-video --help — she'll tell you everything.

But here's the specific slay: it can read a Scenery in XML format and a trajectory also in XML format (for instance produced with gyotoy(1), see below, we'll get there) and produce a movie as would be seen by an observer following this trajectory.

like... you get to ride along with the observer. cinema. 🍿

⚠️ bestie, heads up: the Gyoto plug-in python and the Python module OpenCV-Python must be installed for this. Not optional. No skipping.

And the Python flavor to use can be controlled through the GYOTO_PYTHON environment variable. 💜

🌸 your little companion app 🌸

A companion program, gyotoy(1), can be used to interactively visualize a single geodesic in any Gyoto metric — that's the trajectory of a single photon or massive particle.

one particle. one path. up close and personal. she's the intimate portrait to gyoto's wide shot. 🖼️

😭 the part where I warn you about runtime 😭

Ray-tracing can be very time consuming. Like, go-make-a-snack time consuming. Go-live-your-life time consuming.

BUT. It is possible to interrupt the process at any time by hitting ^C, which will save the already-computed part of the image before exiting the program.

💖 so you don't lose your progress. she saves your work on the way out. queen behaviour.

You can then compute the rest of the image later using the --jmin option. Resume from where you left off. ✨

more of this manual coming up next, don't go anywhere bestie 💅

💅 OPTIONS 💅

okay bestie, this is the part where gyoto shows off. It takes a lot of options, and here's the tea on how they work 🫖

Most options have a long name (like --parameter) and a short name (like -E). When an option takes an argument, that argument has to come right after the short option, no space, like -EPath::Name. For a long option you separate it with exactly one = character, like --parameter=Path::Name. Long options can be abbreviated as long as the abbreviation isn't ambiguous — so --par=Path::Name totally works ✨

Most options can show up several times, and they get processed in the order they appear on the command line. The two positional parameters (input.xml and output.fits) can appear anywhere in the command line — unless they start with a minus character (-), in which case they must come last, after the -- option. no cap 💅

🎀 Getting help

  • --help[=class], -h[class] — If you don't give it a class, it prints a help summary. It's not as wordy as this manual page, but honestly the output of gyoto -h may be more complete and more up to date. If you do specify class, it lists and documents the properties of that class (e.g. "Screen", "Astrobj::Star"). Then it exits the program — unless --list below has only been specified. 👑
  • --list, -l — Prints the list of currently registered Astrobj, Metric, etc., then exits the program. This happens after loading input.xml (if you provided one), so any plug-in specified in the input file is already loaded by then. iconic.
  • --version, -V — Prints the Gyoto version, the ABI compatibility version, and copyright information, then exits. the receipts ✨

🌸 Setting the verbosity level

These options are processed separately from all the others, and they take effect early in the program execution. like they show up early to the party 💅

  • --silent, -s — No output. 🤫
  • --quiet, -q — Minimal output.
  • --verbose[=N], -v[N] — Verbose mode. You can specify verbosity level N.
  • --debug, -d — Insanely verbose. 💀
  • --no-sigfpe — Do not try to raise SIGFPE upon arithmetic exceptions. This option is only meaningful if fenv.h support is built in. Otherwise it's a no-op, because SIGFPE is never raised. (it's giving "I do nothing and I'm proud" 🙈)

🦋 Loading plug-ins

  • --plugins[=[nofail:]plug1[,[nofail:]plug2][...]], -p[[nofail:]plug1[,[nofail:]plug2][...]] — A comma-separated list of Gyoto plugins to load. This overrides the GYOTO_PLUGINS environment variable (see below). Only the last occurrence matters. periodt.

🌈 Selecting a region

You can ray-trace only part of the scenery by handing over the pixel coordinates of the bottom-left corner (i0, j0) and the top-right corner (i1, j1) of the region. Heads up: the bottom-left pixel of the complete image has coordinates i=1 and j=1. You can also specify the step in each direction (di, dj). 🎯

  • --ispec=[i0]:[i1]:[di], -i[i0]:[i1]:[di] — the i-direction spec.
  • --jspec=[j0]:[j1]:[dj], -j[j0]:[j1]:[dj] — the j-direction spec.

Default values for both: x0: 1; x1: npix (see option --resolution below); dx: 1.

  • --ispec=N, -iN — Set both x0 and x1 to N.
  • --jspec=N, -jN — Set both x0 and x1 to N.

💜 Alternate region-selection options:

These are still supported for backward compatibility, but they're deprecated in favour of --ispec and --jspec above. So like… they're the older sibling options, still valid, but the new ones ate 💅

  • --imin=i0 — Default value: 1.
  • --imax=i1 — Default value: npix (see option --resolution below).
  • --di=di — Default value: 1.
  • --jmin=j0 — Default value: 1.
  • --jmax=j1 — Default value: npix (see option --resolution below).
  • --dj=dj — Default value: 1.

👑 Setting the camera position

These parameters are normally provided in the Screen section of input.xml, but you can override them on the command line — for instance to make a movie, by calling gyoto for each movie frame and changing only the option --time. main character energy, fr fr 🎬

  • --time=tobs — The observing time in geometrical units.
  • --fov=angle — The field-of-view of the camera, in radians.
  • --resolution=npix, -rnpix — Number of rows and columns in the output image.
  • --distance=dist — (Coordinate) distance from the observer to the center of the coordinate system, in geometrical units.
  • --paln=Omega — Position angle of the line of nodes, in radians, East of North. This is the angle between the North direction and the line of nodes (see below).
  • --inclination=i — Angle between the plane of the sky and the equator of the coordinate system. The intersection of those two planes is the line of nodes.
  • --argument=theta — Angle in the equatorial plane between the line of nodes and one of the main axes of the coordinate system.

⭐ Miscellaneous

Unsorted option(s) — yes, this is the junk drawer and honestly? we love her 🧚

  • -- — Ends option processing, in case either input.xml or output.fits starts with "-".
  • --nthreads=nth, -Tnth — Number of parallel threads to use. For instance, on a dual-core machine, --nthreads=2 should give you the fastest computation. This option is silently ignored if Gyoto was compiled without POSIX threads support. Note that the metric and the object are replicated for each thread, which can lead to a decrease in performance if either one is memory-intensive. Setting this option to 0 is equivalent to setting it to 1.
  • --nprocesses=nworkers, -Pnworkers — Number of MPI processes to spawn for parallel ray-tracing, in addition to the main gyoto process, which sticks around to manage the computation. Ignored if gyoto was compiled without MPI support. nworkers is the number of workers spawned. The total number of processes is nprocs=nworkers+1. -P0 disables MPI multi-processing, while -P1 uses two processes: the manager and one worker. If nworkers is >0, --nthreads is ignored. Note that the MPI environment usually needs to be set up using some variant of mpirun(1). If mpirun starts several instances of gyoto, nworkers must be >0, but its exact value is ignored, since the set of processes used is exactly the one launched by mpirun. In other words, Gyoto can be called in a number of ways that should be functionally equivalent:
    • let mpirun launch nprocs instances of the gyoto executable:
mpirun -np -Pnprocs gyoto -P1 input.xml output.fits
  • let mpirun launch 1 instance of the gyoto executable, and Gyoto spawn nworkers worker processes:
mpirun -np 1 gyoto -Pworkers input.xml output.fits
  • let mpirun launch 1 instance of the gyoto executable, and nworkers worker processes:
mpirun -np 1 gyoto -P1 input.xml output.fits : \
       -np nworkers gyoto-mpi-worker.version

where version is the ABI compatibility version of gyoto (see gyoto --version).

  • --impact-coords[=impactcoords.fits] — In some circumstances, you may want to perform several computations in which the computed geodesics end up being exactly identical. This is the case, for instance, if you want to experiment with changing the spectrum of a star, or when making a movie of a rotating, optically thick disk. This option gives you a mechanism to not recompute the geodesics in the most simple case, i.e. when:
    • the Screen is always at the same position;
    • the Metric is always exactly the same;
    • the Astrobj is optically thick (no radiative transfer processing is necessary);
    • the location and shape of the Astrobj is always the same.

If --impact-coords is passed without specifying impactcoords.fits, the 8-coordinate vectors of the object and photon at impact point are saved for each point of the Screen. Missing data (no impact) are set to DBL_MAX. These data are saved as a supplementary image HDU in the FITS file, which is identified by its EXTNAME: "Gyoto Impact Coordinates". The FITS keyword "HIERARCH Gyoto Observing Date" of this HDU holds the observing date (in geometrical unit).

If impactcoords.fits is specified, the above mentioned data are read back from this file. The ray-tracing is not performed, but the Gyoto::Astrobj::Generic::processHitQuantities() method is called directly, yielding the same result if the four conditions above are met. The observing date stored in the FITS keyword "HIERARCH Gyoto Observing Date" is compared to the date specified in the screen or using the --time option, and the impact coordinates are shifted in time accordingly.

It is also possible to set the two versions of this option at the same time:

--impact-coords=impactcoords.fits --impact-coords

In this case, the impact coordinates are read from impactcoords.fits, shifted in time, and saved in output.fits.

  • --unit[=unit], -u[unit] — Specify the unit to use for allowing instances of --parameter, until the next instance of --unit.
  • --parameter=Path::Name[=value], -EPath::Name[=value] — Set an arbitrary parameter by name. Parameters can be set in the Astrobj, Metric, etc. using the Path component. For instance,

For instance, assuming the Astrobj in star.xml has a property named "Radius" that can be set in unit "km", and a property named "Spectrum" which has a property named "Temperature", we can set the radius, the temperature and the quantities to compute (a property in the Scenery itself) with:

gyoto -EQuantities=Spectrum \
      -ukm -EAstrobj::Radius=3 \
      -u -EAstrobj::Spectrum::Temperature=1000 \
      star.xml star.fits

gyoto --parameter=Quantities=Spectrum \
      --unit=km --parameter=Astrobj::Radius=3 \
      --unit="" --param=Astrobj::Spectrum::Temperature=1000 \
      star.xml star.fits
  • --xmlwrite=output.xml, -Xoutput.xml — Write the scenery back to an XML file. The new file will contain additional default parameters and reflect the effect of --(astrobj|metric|scenery|screen|spectrometer)-parameter that appear before --xmlwrite. Can appear several times, e.g. to generate several XML files with different settings. 💖

📁 FILES 📁

  • input.xml — bestie this is the gyoto input file, and it's in XML format, no cap. Several examples ship in the source doc/examples directory ✨. Depending on how you installed gyoto, they might already be chillin' on your system somewhere like /usr/share/doc/libgyoto/examples/ 🫶. Okay real talk though: documenting the whole XML file format that Gyoto supports is so beyond the scope of this manpage 💀 — go read the library documentation instead. It might come with your package manager, you can compile it from the Gyoto source, or you can peek it online at http://gyoto.obspm.fr/ 🌐.
  • output.fits — the output image, in FITS format, iconic 💅. But listen: gyoto will not overwrite output.fits unless it's prefixed with an (escaped) !, like this: gyoto in.xml \!out.fits. Protect your files, queen 👑. Also, depending on the Gyoto Quantities and the Spectrometer specified in input.xml, this file may actually be a whole stack of images, not just one 📚. Want the tea on the FITS format? See http://fits.gsfc.nasa.gov/.

🌱 ENVIRONMENT 🌱

  • GYOTO_PLUGINS — Gyoto's astronomical objects and metrics are implemented in plug-ins, periodt. If you wanna use more (or less!!) than the standard plug-ins, set the environment variable GYOTO_PLUGINS to a comma-separated list of plug-ins 💫. gyoto will exit with an error status if it can't load a plug-in you specified — unless that plug-in is prefixed with nofail: in GYOTO_PLUGINS, in which case it just… doesn't fail 😌. Heads up: this environment variable gets overridden by the --plugins command-line parameter, so command line wins, always 💅.

Default value: "stdplug,nofail:lorene" ⭐

Gyoto tries to find plug-ins by first relying on the system's dynamic linker (so paths in e.g. LD_LIBRARY_PATH and ld.so.conf get searched first 🔍). If that fails, it looks in PREFIX/lib/gyoto/ and finally in PREFIX/lib/gyoto/SOVERS/, where PREFIX and SOVERS are two compile-time options. PREFIX is usually /usr/local or /usr 🌸. At the time of writing, SOVERS is 0.0.0 — yes, really, that's the whole version number, she's minimal 🎀.

  • GYOTO_PYTHON — the name of the Python plug-in to use for mk-video (typically either "python3" or a more specific version like "python3.12" 🐍). By default, several names are tried, so she'll figure it out herself, main character energy fr fr ✨.

🚪 EXIT STATUS 🚪

gyoto returns 0 upon success 🎉, 1 if it's unable to parse the command line or to interpret input.xml 😭, and a CFITSIO error code if something goes wrong when trying to open, write to, or close output.fits 💀. For the full deets, refer to the CFITSIO documentation 📖.

✍️ AUTHOR ✍️

Thibaut Paumard <thibaut.paumard@obspm.fr> wrote this manual 🫶. Legend behavior, honestly.

👀 SEE ALSO 👀

and that's the whole page bestie!! 💖✨🎀🦋🌸💅🫶🔥👑🌈⭐💜🍓🧚

This gorgeous little manual comes from the Science section, dated January 2024, and it's page GYOTO(1) — go forth and simulate some spacetime, you absolute icon 💫🪐

📦 where this page comes from