Workspace agendas

At their simplest, workspace agendas uses a set of Workspace methods that combined requires a set of Workspace variables to produce another set of workspace variables. All agendas have access to the global workspace but are expected to only directly require a limited subset to produce their outputs.

Workspace agendas are defined in the workspace_agendas.cpp file. The workspace agenda definitions are located in the wsa_data map object. The name of the agenda is the key of the map. Throughout this text, we will use agendax to represent a generic agenda name. The agenda object itself is a struct with the following fields:

  • desc - a description of the agenda as a string.

  • outputs - the workspace variables that are produced/output by the agenda as a list of strings.

  • inputs - the workspace variables that are consumed by the agenda as a list of strings.

  • enum_options - a list of strings that are the options for the agenda. Defaults to empty.

  • enum_defaults - the default enum option for the agenda. Defaults to no-default by being empty.

The two enum-variables, if set, will generate workspace methods that allow setting the agenda to a specific named option. This is useful for agendas that have known “modes”. However, it puts some constraints on the implementation of the agenda. The implementor must implement a method get_agendax(const std::string&) in the workspace_agenda_creator.h and workspace_agenda_creator.cpp files. Please see existing options in those files for examples.

How to add a workspace agenda?

The easiest way to add an agenda is to copy an existing agenda. Go to the workspace_agendas.cpp file. Copy an existing agenda and modify it to fit your needs.

If you want to provide user-friendly settings for your agenda, use the enum_options and enum_defaults fields. You will need to add the get_agendax(const std::string&) method in the workspace_agenda_creator.h and workspace_agenda_creator.cpp files if you do so, or you will encounter a compile time error. Adding these methods is once again easy to do by copying an existing method and modifying it to fit your needs.

Note

Keep the switch-statement structure of the get_agendax(const std::string&) methods. All modern compilers will warn when options are missing from the switch statements. Do not solve this warning by adding a default case to the switch statement as this will mute all future warnings. All cases should be explicitly handled.

What qualifies a workspace agenda?

A method or a set of methods must be able to use the workspace agenda to produce a set of desired workspace variables. Generally, if you can keep the number of inputs limited and the number of outputs fixed, you may consider a workspace agenda. However, overpopulating the workspace with agendas is not recommended. So please reuse existing ones as appropriate.

Take ray_path_observer_agenda as an example. The different ways we can define a path from an observer to a background is practically limitless. However, if we are just interested in spectral_radiance for some observer and frequency, we know that we just need the background radiation from the background of the observed ray_path and the state of the atmosphere along the path. So a method like measurement_vectorFromOperatorPath(), which takes a set of frequencies and a set of observers, may effectively ignore the complexity of computing the ray_path internally, and leave that to the workspace agenda.

Generated files

There are several files generated for both the pure C++ and for the python interface.

Check these if anything is unclear after reading this documentation to ensure there are no bugs in the generated code.

These are the pure C++ files:

  • auto_wsa.h: Contains recursive agenda call handling logic. Also defines the workspace methods agendaxExecute and agendaxSet interfaces.

  • auto_wsa.cpp: Creates a workspace variable with the name of the agenda. Implements what is in the namesake header file. Also implements the logic for documenting these methods.

  • auto_wsa_options.h: Implements the options used in set-methods. These are stripped down versions of the standard ARTS options.

  • auto_agenda_operators.h: Defines a callable workspace group to represent the agenda. The type is called agendaxOperator.

  • auto_agenda_operators.cpp: Implements workspace methods agendaxExecuteOperator and agendaxSetOperator. The former executes the workspace group from the header file, the latter allows setting the agenda to call a custom operator, e.g., a python function.

This is the only python interface files:

  • py_auto_agenda_operators.cpp: Implements the GIL-safe agendaxOperator callback types. It should be possible to create these using any python callable, such as a def method or a class that implements __call__. The error should be propagated as if it were in python.

Workspace agenda naming convention

Workspace agendas should be named in snake_case as they are also Workspace groups.

Do not hesitate to implement helpers

Several agendas have helper methods to make the user interface easier. These methods should follow a simple naming convention.