ESOREX(1)

📦
version 3.13.11 · 5 versions
, in ubuntu stonking

💅 esorex(1) — ESO Recipe Execution Tool 💅

okay so this is the User Commands section of the manual, bestie. buckle up, it's a long one and it EATS. 🔥

🌸 NAME 🌸

esorex — the ESO Recipe Execution Tool. that's it, that's the name, iconic behaviour honestly 👑

✨ SYNOPSIS ✨

esorex [esorex-options] recipe [recipe-options] sof

there it is. options, then a recipe, then recipe options, then the sof. in that order. slay. 💖

🦋 DESCRIPTION 🦋

EsoRex is the ESO Recipe Execution Tool. bestie it can list, configure and execute CPL-based recipes straight from the command line. no GUI, no mouse, just vibes ✨

so here's the lore: one of the features CPL gives you is the ability to make data-reduction algorithms that run as plugins (aka dynamic libraries). these little guys are called recipes</>, and ngl they're like… one of the main characters of the whole CPL data-reduction development environment 🫶

the catch? because these recipes are dynamic libraries, you literally cannot run them directly from the command line. not possible. so ESO provides a few tools to do it for you, which saves recipe developers from having to write that whole application themselves. one of those tools is GASGANO (the GUI-based one) and the other is EsoRex, which runs from the command line — and that's the one we're describing right here. periodt. 💅

🎀 OPTIONS 🎀

every single one of these can also be set through an environment variable, and every default is in the brackets. iykyk.
  • --help — display this help and exit. and if you also gave a recipe name? then you get help for that recipe too, as a little treat. [TRUE]
  • --version — display version information and exit. [FALSE]
  • --check-sof-exist — when TRUE, every single input file has to exist and be readable before the recipe gets called. no sneaky missing files allowed bestie 🚫 this one can also be set with the environment variable ESOREX_CHECK_SOF_EXIST. [FALSE]
  • --config — the configuration file to use for EsoRex. can also be set with the environment variable ESOREX_CONFIG. []
  • --create-config — creates a configuration file for Esorex. if it's set to TRUE, a config file called esorex.rc gets created in the .esorex directory inside the user's $HOME. if you give a filename, then the config file gets created accordingly instead. and if you gave a recipe on the command line, then the config file gets created for the recipe instead — that one's called recipename.rc. ⚠️ heads up: an existing file will be overwritten, but a backup gets copied to filename.rc.bak in the same directory, so breathe. and if the filename ends with the .json extension, a machine-readable JSON format is used instead. can also be set with the environment variable ESOREX_CREATE_CONFIG. [FALSE]
  • --link-dir — the directory where a symbolic link to each of the product files should be written. the actual on/off switch for whether that link gets made at all is the --suppress-link option. can also be set with the environment variable ESOREX_LINK_DIR. [/tmp]
  • --log-dir — directory where the logfile goes. can also be set with the environment variable ESOREX_LOG_DIR. [.]
  • --log-file — filename of the logfile. can also be set with the environment variable ESOREX_LOG_FILE. [esorex.log]
  • --log-level — controls the severity level of messages printed to the logfile. can also be set with the environment variable ESOREX_LOG_LEVEL. values: <debug | info | warning | error | off> [info]
  • --no-datamd5 — disables the computation of the MD5 data hash for FITS product files. can also be set with the environment variable ESOREX_NO_DATAMD5. [FALSE]
  • --no-checksum — disables the computation of the standard FITS product checksums. can also be set with the environment variable ESOREX_NO_CHECKSUM. [FALSE]
  • --man-page — display a manual page for the specified recipe, then exit. note that this option only applies to recipes, and it does absolutely nothing for esorex by itself. see also the --help option. can also be set with the environment variable ESOREX_MAN_PAGE. [FALSE]
  • --mem-check — report on memory status at completion of recipe execution. can also be set with the environment variable ESOREX_MEM_CHECK. [FALSE]
  • --msg-level — controls the severity level of messages printed to the terminal. can also be set with the environment variable ESOREX_MSG_LEVEL. values: <debug | info | warning | error | off> [info]
  • --output-dir — the directory where the product files should be finally moved to. and yes, every product is first created in the current dir and then relocated, that's just how it is. can also be set with the environment variable ESOREX_OUTPUT_DIR. [.]
  • --output-prefix — prefix applied to any output file. for example, specifying pre would translate filename.fits into pre_0000.fits. ✨ see also the --suppress-prefix option. can also be set with the environment variable ESOREX_OUTPUT_PREFIX. [out]
  • --output-readonly — when TRUE, any existing product files in the specified output directory get set to read-only, for user, group and other. if FALSE, then EsoRex uses the default permissions for that account/directory. destroy any pre-existing files. this option exists for the Paranal operations environment. this option can additionally be used to prevent EsoRex from overwriting pre-existing files. can also be set with the environment variable ESOREX_OUTPUT_READONLY. [FALSE]
  • --paf-config — configuration file for creation of PAF files (deprecated 😬). can also be set with the environment variable ESOREX_PAF_CONFIG. []
  • --params — list the input parameters and their current settings (whether they came from the command line or a configuration file) for the esorex application. parameters are labelled using the parameter's alias. and if you also specified a recipe, then the list of its parameters gets generated in the same way too. can also be set with the environment variable ESOREX_PARAMS. [FALSE]
  • --products-sof — output file which contains the FITS files created by the recipe. if the filename ends with the .json extension then a machine-readable JSON format will be used. can also be set with the environment variable ESOREX_PRODUCTS_SOF. []
  • --recipes — display a list of all available recipes (the ones that are available in the directory tree specified with --recipe-dir). can also be set with the environment variable ESOREX_RECIPES. [FALSE]
  • --recipe-config — configuration file for any selected recipe. can also be set with the environment variable ESOREX_RECIPE_CONFIG. []
  • --recipe-dir — directory containing recipe libraries. ngl this one goes feral: esorex will recursively search not only the directory you specified, but every single sub-directory below it as well 🌀 multiple directory heads may be specified by separating the starting paths with colons (:). can also be set with the environment variable ESOREX_PLUGIN_DIR. [.]
  • --show-hidden — when TRUE, recipe parameters that the recipe declared as hidden get shown in the output of the help and man page options. 👀 the hidden ones. revealed. [FALSE]
  • --suppress-link — when TRUE, no symbolic link is created to the output product. but if FALSE, then a symbolic link gets created in the directory specified with the --link-dir option, for each product the recipe creates. can also be set with the environment variable ESOREX_SUPPRESS_LINK. [TRUE]
  • --suppress-prefix — when TRUE, the original name of the output product, exactly as produced by the recipe, is maintained. if FALSE, then the name of the output file gets changed to the prefix_number format, and you can change that prefix with the --output-prefix option. can also be set with the environment variable ESOREX_SUPPRESS_PREFIX. [FALSE]
  • --time — measure and show the recipe's execution time ⏱️ can also be set with the environment variable ESOREX_TIME. [FALSE]
  • --unload-plugin — when TRUE, the plugin is unloaded after execution. if FALSE, the plugin is not unloaded after processing, which is the move when you want software like, e.g., valgrind to be able to debug the executed recipe. 🐛 can also be set with the environment variable ESOREX_UNLOAD_PLUGIN. [TRUE]

🌈 ENVIRONMENT 🌈

all options can be set as environment parameters as well. bestie, literally all of them. see the previous paragraph for the details 💖

🍓 FILES 🍓

  • /etc/esorex.rc $HOME/.esorex/esorex.rc — default configuration files.

the configuration file contains the EsoRex options, minus the -- switch, but prefixed with esorex.caller.. blank lines are ignored, and any line beginning with # is treated as a comment. 🙈

here's an example configuration file:

# Example EsoRex configuration file
#
esorex.caller.recipe-dir=/home/username/EsoRex/Plugins
esorex.caller.log-dir=.
esorex.caller.log-file=esorex.log
esorex.caller.log-file=esorex.log
esorex.caller.output-dir=.
esorex.caller.output-prefix=out_

(yes the log-file line is in there twice in the example. we don't ask questions, we just respect the icon 💅)

  • filename.sof — a sof file contains a list of the input data. this data is specified in a sof file (which is, and i cannot stress this enough, just a text file 🌸), where each input file is specified with its associated classification and category. the format of each line in the sof file is as follows:
full-path-to-file  classification

optionally, a third column may be provided. the permitted values are either RAW or CALIB. this is for when a recipe does not identify the type of input file — but since all ESO recipes are required to do so, this column is typically not needed. so like, it's the emergency backup column. 🫶

an example sof file, for the mythological "ZIMOS" instrument, might look like this:

/data/mos/ZIMOS.03-12-26T01:05:06.fits  MOS_SCIENCE
/data/mos/ZIMOS.03-12-26T01:26:00.fits  MOS_SCIENCE
/data/mos/ZIMOS.03-12-26T01:47:04.fits  MOS_SCIENCE
/data/cal/master_bias4.fits             MASTER_BIAS
/data/cal/grs_LR_red.3.tfits            GRISM_TABLE
/data/gasgano/extract_table2.fits       EXTRACT_TABLE
/data/cal/badpixel.3.tfits              CCD_TABLE

for a concrete example for a specific instrument, go check the documentation for that instrument. 🧚

🫶 HINTS 🫶

okay bestie, this is the part where I hold your hand through the little traps that are absolutely real and absolutely annoying. no gatekeeping here 💅

📁 File permissions

so listen. if you're using a recipe with the --suppress-prefix option, AND --output-dir is pointing at the current working directory, then here's the tea: the first run of that recipe works fine. cute. but the subsequent runs? they may just fail on you 😭

why tho? because output products get handed read-only permission — and it's genuinely on purpose, to avoid the potential inadvertent loss of products. precious little files, they're protected 🥺. but the recipe itself can't modify those permissions, so when it tries to create the file again, it just... can't. it fails.

the solution (yes, beyond just using a different output directory or different prefixes) is to change the permission of those output files, or delete them, before you run that recipe again. do that and you're slaying again ✨

and btw this whole situation is less likely to bite you in EsoRex v2+, because --output-overwrite got replaced with --output-readonly (which is disabled by default, thank u). but a determined user can still absolutely end up here — and if you do, those non-readable products need their permissions changed, exactly like I said above. no cap.

⚙️ Configuration files

when you're creating configuration files, the vibe check is this:

  • if the recipe is provided on the command line, then EsoRex generates the configuration file for that recipe 💖
  • if no recipe name is given, then EsoRex generates a configuration file for EsoRex itself 🌸

and where do all these config files live? every single one of them gets written in the $HOME/.esorex/ directory. that's the spot. that's their home. periodt 🏠

🧠 Memory checking

you wanna know if the recipe you're running is leaking memory? iconic of you honestly. just enable the --mem-check option and EsoRex will do exactly that 🔍

then, at the conclusion of the recipe execution — and after memory deallocation — a list of all remaining allocated memory gets printed to your screen. that's your receipt 🧾

and if there are no memory leaks? then no additional output is displayed. silence is golden, bestie 🌈

🐛 REPORTING BUGS 🐛

found something broken? it's not your fault, I promise. report bugs to <cpl-help@eso.org>. that's the address, write it down, send the email 💌

Copyright 2003-2024, European Southern Observatory.

okay that's the whole page, bestie, you made it to the end 🎀 this was esorex, part of EsoRex, and the page you just read is dated July 2026 ✨ go forth and reduce your spectra, you absolute main character 💅🦋

📦 where this page comes from