ARTS  2.4.0(git:4fb77825)
arts_api.h File Reference

Go to the source code of this file.

Classes

struct  VariableStruct
 Representation of ARTS WSVs. More...
 
struct  VariableValueStruct
 Representation of ARTS values. More...
 
struct  MethodStruct
 Representation of workspace methods. More...
 
struct  VersionStruct
 ARTS version. More...
 
struct  CovarianceMatrixBlockStruct
 Covariance matrix block. More...
 

Macros

#define DLL_PUBLIC   __attribute__((visibility("default")))
 

Functions

DLL_PUBLIC void include_path_push (const char *path)
 Add include path. More...
 
DLL_PUBLIC void include_path_pop ()
 Remove last include path. More...
 
DLL_PUBLIC void data_path_push (const char *path)
 Add data path. More...
 
DLL_PUBLIC void data_path_pop ()
 Remove last data path. More...
 
DLL_PUBLIC void initialize ()
 Initalize ARTS runtime. More...
 
DLL_PUBLIC void finalize ()
 Finalize ARTS runtime. More...
 
DLL_PUBLIC const char * get_error ()
 Get most recent error. More...
 
DLL_PUBLIC void set_basename (const char *name)
 Set the ARTS basename. More...
 
DLL_PUBLIC Agendaparse_agenda (const char *filename)
 Parse Controlfile. More...
 
DLL_PUBLIC Agendacreate_agenda (const char *name)
 Create Agenda. More...
 
DLL_PUBLIC void agenda_add_method (Agenda *a, const Index id, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
 Add method to agenda. More...
 
DLL_PUBLIC void agenda_insert_callback (Agenda *a, void(*f)(InteractiveWorkspace *))
 Insert callback into agenda. More...
 
DLL_PUBLIC void agenda_insert_set (InteractiveWorkspace *ws, Agenda *a, long id, long group_id)
 Insert a set method into an agenda. More...
 
DLL_PUBLIC void agenda_append (Agenda *dst, const Agenda *src)
 Append agendas. More...
 
DLL_PUBLIC void agenda_clear (Agenda *a)
 Clear Agenda. More...
 
DLL_PUBLIC const char * execute_agenda (InteractiveWorkspace *workspace, const Agenda *a)
 Execute Agenda. More...
 
DLL_PUBLIC void destroy_agenda (Agenda *a)
 Destroy Agenda. More...
 
DLL_PUBLIC InteractiveWorkspacecreate_workspace (const Index verbosity=1, const Index agenda_verbosity=0)
 Create new workspace. More...
 
DLL_PUBLIC void destroy_workspace (InteractiveWorkspace *workspace)
 Destroy given workspace. More...
 
DLL_PUBLIC unsigned long get_number_of_groups ()
 Return number of WSV groups. More...
 
DLL_PUBLIC const char * get_group_name (int i)
 Get pointer to name of given group. More...
 
DLL_PUBLIC unsigned long get_number_of_methods ()
 Return number of WSMs. More...
 
DLL_PUBLIC MethodStruct get_method (Index i)
 Return MethodStruct describing method with index i. More...
 
DLL_PUBLIC const char * get_method_g_in (Index i, Index j)
 Get name of generic input argument. More...
 
DLL_PUBLIC const char * get_method_g_in_default (Index i, Index j)
 Get default value of generic input argument. More...
 
DLL_PUBLIC const char * get_g_in_nodef ()
 Get string defining missing default parameter. More...
 
DLL_PUBLIC const char * get_method_g_out (Index i, Index j)
 Get name value of generic output argument. More...
 
DLL_PUBLIC const char * execute_workspace_method (InteractiveWorkspace *workspace, long id, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
 Execute workspace method. More...
 
DLL_PUBLIC const char * method_print_doc (long id)
 Print method documentation. More...
 
DLL_PUBLIC long lookup_workspace_variable (const char *s)
 Lookup workspace variable by name. More...
 
DLL_PUBLIC unsigned long get_number_of_variables ()
 Number of defined WSVs. More...
 
DLL_PUBLIC VariableStruct get_variable (Index i)
 Get WSV by index. More...
 
DLL_PUBLIC VariableValueStruct get_variable_value (InteractiveWorkspace *workspace, Index id, Index group_id)
 Get value WSV in given workspace. More...
 
DLL_PUBLIC void * get_variable_data_pointer (InteractiveWorkspace *workspace, Index id)
 Get data pointer to the WSV variable. More...
 
DLL_PUBLIC CovarianceMatrixBlockStruct get_covariance_matrix_block (CovarianceMatrix *m, long block_index, bool inverse)
 Return block of covariance matrix. More...
 
DLL_PUBLIC const char * set_variable_value (InteractiveWorkspace *workspace, long id, long group_id, VariableValueStruct value)
 Sets the value of a WSV in a given workspace. More...
 
DLL_PUBLIC long add_variable (InteractiveWorkspace *workspace, long group_id, const char *name)
 Add variable of given type to workspace. More...
 
DLL_PUBLIC void erase_variable (InteractiveWorkspace *workspace, long id, long group_id)
 Erase variable from workspace. More...
 
DLL_PUBLIC VersionStruct get_version ()
 Get ARTS Version. More...
 

Macro Definition Documentation

◆ DLL_PUBLIC

#define DLL_PUBLIC   __attribute__((visibility("default")))

Definition at line 32 of file arts_api.h.

Function Documentation

◆ add_variable()

DLL_PUBLIC long add_variable ( InteractiveWorkspace workspace,
long  group_id,
const char *  name 
)

Add variable of given type to workspace.

This adds and initializes a variable in the current workspace and also adds a new entry to the global wsv_data array and updates WsvMap.

Parameters
workspaceThe pointer to the InteractiveWorkspace object where to create the object.
group_idThe index of the group of the variable
namePointer to a null-terminated string containing the name of the variable. If nullptr, a name will be auto-generated.
Returns
The index which indentifies the variable in the given workspace.

Definition at line 637 of file arts_api.cc.

References InteractiveWorkspace::add_variable().

◆ agenda_add_method()

DLL_PUBLIC void agenda_add_method ( Agenda a,
const Index  id,
unsigned long  n_args_out,
const long *  args_out,
unsigned long  n_args_in,
const long *  args_in 
)

Add method to agenda.

Add a method to the given agenda.

Parameters
aPointer to agenda object.
idIndex of the method to add to the agenda.
n_args_outNumber of non-generic and generic output arguments.
args_outIndices of the output variables.
n_args_inNumber of non-generic and generic input arguments.
args_inIndices of the input variables.

◆ agenda_append()

DLL_PUBLIC void agenda_append ( Agenda dst,
const Agenda src 
)

Append agendas.

Appends the methods in agenda src to agenda dst. This can be used to emulate include statements in agenda definitions.

Parameters
dstThe agenda to append the methods to
srcThe agenda whose methods to append to src

Definition at line 171 of file arts_api.cc.

References methods(), Agenda::Methods(), and Agenda::push_back().

◆ agenda_clear()

DLL_PUBLIC void agenda_clear ( Agenda a)

Clear Agenda.

Resets a given agenda to be emtpy.

Parameters
aPointer to agenda object.

Definition at line 178 of file arts_api.cc.

◆ agenda_insert_callback()

DLL_PUBLIC void agenda_insert_callback ( Agenda a,
void(*)(InteractiveWorkspace *)  f 
)

Insert callback into agenda.

Inserts callback to the given function object into the agenda.

Definition at line 149 of file arts_api.cc.

References InteractiveWorkspace::add_callback(), global_data::md_data, and Agenda::push_back().

◆ agenda_insert_set()

DLL_PUBLIC void agenda_insert_set ( InteractiveWorkspace ws,
Agenda a,
long  id,
long  group_id 
)

Insert a set method into an agenda.

This inserts a set method into the given agenda which sets the a workspace variable given by its ID to to the value it currently has in the given workspace.

Parameters
Pointerto the workspace
Pointerto the agenda
Pointerto the callback function object
Languagetype of the callback.

Definition at line 94 of file arts_api.cc.

References global_data::MdMap, Agenda::push_back(), and global_data::wsv_group_names.

◆ create_agenda()

DLL_PUBLIC Agenda* create_agenda ( const char *  name)

Create Agenda.

Creates an empyt agenda.

Parameters
[in]nameName of the agenda
Returns
Pointer to the newly created agenda.

Definition at line 88 of file arts_api.cc.

References Agenda::set_name().

◆ create_workspace()

DLL_PUBLIC InteractiveWorkspace* create_workspace ( const Index  verbosity = 1,
const Index  agenda_verbosity = 0 
)

Create new workspace.

Returns
Pointer to a newly created InteractiveWorkspace object.

Definition at line 191 of file arts_api.cc.

References ARTS::Var::verbosity().

◆ data_path_pop()

DLL_PUBLIC void data_path_pop ( )

Remove last data path.

Remove the most recently added data path. Will result in an exception if the data path is empty.

Definition at line 58 of file arts_api.cc.

References Parameters::datapath, and parameters.

◆ data_path_push()

DLL_PUBLIC void data_path_push ( const char *  path)

Add data path.

Adds a given path to the ARTS data path.

Parameters
[in]pathPointer to cstring containing the path to add to the data path.

Definition at line 56 of file arts_api.cc.

References Parameters::datapath, and parameters.

◆ destroy_agenda()

DLL_PUBLIC void destroy_agenda ( Agenda a)

Destroy Agenda.

Parameters
aPointer to the agenda.

Definition at line 186 of file arts_api.cc.

◆ destroy_workspace()

DLL_PUBLIC void destroy_workspace ( InteractiveWorkspace workspace)

Destroy given workspace.

Definition at line 196 of file arts_api.cc.

◆ erase_variable()

DLL_PUBLIC void erase_variable ( InteractiveWorkspace workspace,
long  id,
long  group_id 
)

Erase variable from workspace.

This variable removes a variable from the workspace and the global wsv_data and WsvMap. This is likely to invalidate indices of existing variables so it should be used with care.

Parameters
workspacePointer to the InteractiveWorkspace object owning the variable
idThe index of the variable
group_idThe index of the group of the variable

Definition at line 644 of file arts_api.cc.

References InteractiveWorkspace::erase_variable().

◆ execute_agenda()

DLL_PUBLIC const char* execute_agenda ( InteractiveWorkspace workspace,
const Agenda a 
)

Execute Agenda.

Executes the given agenda on a given workspace.

Parameters
workspacePointer of the InteractiveWorkspace object to execute the agenda on.
aPointer to the agenda to execute.
Returns
NULL if execution was successfull, otherwise pointer to the c_str holding the error message from ARTS.

Definition at line 180 of file arts_api.cc.

References InteractiveWorkspace::execute_agenda(), and Agenda::set_main_agenda().

◆ execute_workspace_method()

DLL_PUBLIC const char* execute_workspace_method ( InteractiveWorkspace workspace,
long  id,
unsigned long  n_args_out,
const long *  args_out,
unsigned long  n_args_in,
const long *  args_in 
)

Execute workspace method.

Execute workspace method with given index. Input arguments are passed using pointers to two arrays holding the indices of the input arguments and the output arguments, respectively. The length of the input (output) arguments must of course match the number of non-generic and generic input (output) arguments.

Parameters
iThe index of the WSM
args_outPointer to the array holding the indices of the output WSVs.
args_inPointer to the array holding the indices of the input WSVs.
Returns
NULL if execution of workspace method was successful, pointer to c_str hodling the ARTS error message otherwise.

Definition at line 262 of file arts_api.cc.

References copy_output_and_input(), and InteractiveWorkspace::execute_workspace_method().

◆ finalize()

DLL_PUBLIC void finalize ( )

Finalize ARTS runtime.

Deletes the error buffer.

Definition at line 62 of file arts_api.cc.

◆ get_covariance_matrix_block()

DLL_PUBLIC CovarianceMatrixBlockStruct get_covariance_matrix_block ( CovarianceMatrix m,
long  block_index,
bool  inverse 
)

Return block of covariance matrix.

Parameters
mPointer to covariance matrix from which to return the block.
block_indexIndex of the block to return.
inverseWhether the block should be returned from the list of inverse blocks or not.
Returns
Returns the block identified by the given pointer represented by CovarianceMatrixBlockStruct.

Definition at line 467 of file arts_api.cc.

References Block::dense, CovarianceMatrix::get_blocks(), MatrixView::get_c_array(), Sparse::get_column_index_pointer(), Block::get_column_range(), Block::get_dense(), Sparse::get_element_pointer(), Range::get_extent(), Block::get_indices(), CovarianceMatrix::get_inverse_blocks(), Block::get_matrix_type(), Block::get_row_range(), Sparse::get_row_start_pointer(), Block::get_sparse(), Range::get_start(), CovarianceMatrixBlockStruct::indices, and Sparse::nnz().

◆ get_error()

DLL_PUBLIC const char* get_error ( )

Get most recent error.

Returns
Pointer to the c string holding the most recent error message.

Definition at line 66 of file arts_api.cc.

References string_buffer.

◆ get_g_in_nodef()

DLL_PUBLIC const char* get_g_in_nodef ( )

Get string defining missing default parameter.

Definition at line 468 of file arts_api.h.

References NODEF.

◆ get_group_name()

DLL_PUBLIC const char* get_group_name ( int  i)

Get pointer to name of given group.

Definition at line 204 of file arts_api.cc.

References global_data::wsv_group_names.

◆ get_method()

DLL_PUBLIC MethodStruct get_method ( Index  i)

Return MethodStruct describing method with index i.

Definition at line 211 of file arts_api.cc.

References global_data::md_data.

◆ get_method_g_in()

DLL_PUBLIC const char* get_method_g_in ( Index  i,
Index  j 
)

Get name of generic input argument.

Parameters
[in]iThe index of the WSM
[in]Theindex of the generic input arguments
Returns
Pointer to c_str holding the name of the input argument as defined in methods.cc.

Definition at line 246 of file arts_api.cc.

References global_data::md_data.

◆ get_method_g_in_default()

DLL_PUBLIC const char* get_method_g_in_default ( Index  i,
Index  j 
)

Get default value of generic input argument.

Parameters
[in]iThe index of the WSM
[in]jThe index of the generic input argument
Returns
Pointer to c_str holding the default value as defined in methods.cc.

Definition at line 250 of file arts_api.cc.

References global_data::md_data.

◆ get_method_g_out()

DLL_PUBLIC const char* get_method_g_out ( Index  i,
Index  j 
)

Get name value of generic output argument.

Parameters
[in]iThe index of the WSM
[in]jThe index of the generic output argument
Returns
Pointer to c_str holding the name of the output argument as defined in methods.cc.

Definition at line 258 of file arts_api.cc.

References global_data::md_data.

◆ get_number_of_groups()

DLL_PUBLIC unsigned long get_number_of_groups ( )

Return number of WSV groups.

Definition at line 202 of file arts_api.cc.

References global_data::wsv_group_names.

◆ get_number_of_methods()

DLL_PUBLIC unsigned long get_number_of_methods ( )

Return number of WSMs.

Definition at line 209 of file arts_api.cc.

References global_data::md_data.

◆ get_number_of_variables()

DLL_PUBLIC unsigned long get_number_of_variables ( )

Number of defined WSVs.

Definition at line 293 of file arts_api.cc.

References Workspace::wsv_data.

◆ get_variable()

DLL_PUBLIC VariableStruct get_variable ( Index  i)

Get WSV by index.

Parameters
Theindex of the WSV
Returns
VariableStruct representing the WSV

Definition at line 295 of file arts_api.cc.

References WsvRecord::Description(), WsvRecord::Group(), WsvRecord::Name(), and Workspace::wsv_data.

◆ get_variable_data_pointer()

DLL_PUBLIC void* get_variable_data_pointer ( InteractiveWorkspace workspace,
Index  id 
)

Get data pointer to the WSV variable.

Initalize uninitialized WSV variable

Parameters
workspacePointer to a InteractiveWorkspace object.
idIndex of the workspace variable.
Returns
void * to the data

Definition at line 463 of file arts_api.cc.

◆ get_variable_value()

DLL_PUBLIC VariableValueStruct get_variable_value ( InteractiveWorkspace workspace,
Index  id,
Index  group_id 
)

Get value WSV in given workspace.

Parameters
workspacePointer to a InteractiveWorkspace object.
idIndex of the workspace variable.
group_idIndex of the group the variable belongs to.
Returns
VariableValueStruct providing access to the variable.

Definition at line 300 of file arts_api.cc.

References ConstVectorView::empty(), ConstMatrixView::empty(), ConstTensor3View::empty(), ConstTensor4View::empty(), ConstTensor5View::empty(), ConstTensor6View::empty(), ConstTensor7View::empty(), VectorView::get_c_array(), MatrixView::get_c_array(), Tensor3View::get_c_array(), Tensor4View::get_c_array(), Tensor5View::get_c_array(), Tensor6View::get_c_array(), Tensor7View::get_c_array(), Sparse::get_column_index_pointer(), Sparse::get_element_pointer(), Sparse::get_row_start_pointer(), InteractiveWorkspace::is_initialized(), ConstTensor4View::nbooks(), ConstTensor5View::nbooks(), ConstTensor6View::nbooks(), ConstTensor7View::nbooks(), ConstMatrixView::ncols(), Sparse::ncols(), ConstTensor3View::ncols(), ConstTensor4View::ncols(), ConstTensor5View::ncols(), ConstTensor6View::ncols(), ConstTensor7View::ncols(), ConstVectorView::nelem(), ConstTensor7View::nlibraries(), Sparse::nnz(), ConstTensor3View::npages(), ConstTensor4View::npages(), ConstTensor5View::npages(), ConstTensor6View::npages(), ConstTensor7View::npages(), ConstMatrixView::nrows(), Sparse::nrows(), ConstTensor3View::nrows(), ConstTensor4View::nrows(), ConstTensor5View::nrows(), ConstTensor6View::nrows(), ConstTensor7View::nrows(), ConstTensor5View::nshelves(), ConstTensor6View::nshelves(), ConstTensor7View::nshelves(), ConstTensor6View::nvitrines(), ConstTensor7View::nvitrines(), and global_data::wsv_group_names.

◆ get_version()

DLL_PUBLIC VersionStruct get_version ( )

Get ARTS Version.

This function returns the ARTS version number as a double precision floating point number.

Returns
The ARTS version.

Definition at line 649 of file arts_api.cc.

References ARTS_FULL_VERSION, VersionStruct::major, VersionStruct::minor, and VersionStruct::revision.

◆ include_path_pop()

DLL_PUBLIC void include_path_pop ( )

Remove last include path.

Remove the most recently added include path. Will result in an exception if the include path is empty.

Definition at line 54 of file arts_api.cc.

References Parameters::includepath, and parameters.

◆ include_path_push()

DLL_PUBLIC void include_path_push ( const char *  path)

Add include path.

Pushes a given path to the back of the include path.

Parameters
[in]pathPointer to cstring containing the path to add to the include path.

Definition at line 50 of file arts_api.cc.

References Parameters::includepath, and parameters.

◆ initialize()

DLL_PUBLIC void initialize ( )

Initalize ARTS runtime.

This function must be called before any other function to initialize the ARTS C API otherwise bad things will probably happen.

Definition at line 60 of file arts_api.cc.

References InteractiveWorkspace::initialize().

◆ lookup_workspace_variable()

DLL_PUBLIC long lookup_workspace_variable ( const char *  s)

Lookup workspace variable by name.

Parameters
sPointer to c string holding the name of the variable.
Returns
Index of the variable or -1 if no variable with the given name exists.

Definition at line 285 of file arts_api.cc.

References Zeeman::end(), and Workspace::WsvMap.

◆ method_print_doc()

DLL_PUBLIC const char* method_print_doc ( long  id)

Print method documentation.

This prints the documentation of the method as it is found for example in the HTML browser to the stream buffer and returns a pointer to it.

Parameters
idThe id of the method.
Returns
Pointer to c string holding the documentation of the method

Definition at line 274 of file arts_api.cc.

References global_data::md_data, and string_buffer.

◆ parse_agenda()

DLL_PUBLIC Agenda* parse_agenda ( const char *  filename)

Parse Controlfile.

Parses a controlfile into an Agenda and returns a handle to to this agenda, which can be executed on a workspace using execute_agenda(...).

Note that parsing the same controlfile twice fails if this controlfile creates new WSVs.

Parameters
{in]filename The path to the controlfile relative to the ARTS search path.
Returns
Pointer to the agenda holding the parsed controlfile or NULL if an error occurred during parsing.

Definition at line 73 of file arts_api.cc.

References ArtsParser::parse_tasklist(), Agenda::set_main_agenda(), Agenda::set_name(), and verbosity_at_launch.

◆ set_basename()

DLL_PUBLIC void set_basename ( const char *  name)

Set the ARTS basename.

The basename is a global variable that is used in some cases by some WSMs for example to store or read data.

Definition at line 68 of file arts_api.cc.

References out_basename.

◆ set_variable_value()

DLL_PUBLIC const char* set_variable_value ( InteractiveWorkspace workspace,
long  id,
long  group_id,
VariableValueStruct  value 
)

Sets the value of a WSV in a given workspace.

This method can be used to set the value of an ARTS WSV from external data. Currently supported data types are:

For Index and Numeric the data pointer of the VariableValueStruct is assumed to point to the value to set the WSV to. For variables of type String the data pointer is interpreted as pointer to a c_str. For ArrayOfString the data pointer is assumed to point to an array of pointers to c_str. For Vectors and Matrix data is assumed to point an array of double with c-style memory layout and size given by the corresponding values in the dimension field of VariableValueStruct.

Parameters
workspacePointer to a InteractiveWorkspace object.
idIndex of the workspace variable.
group_idIndex of the group the variable belongs to.
Returns
Poiter to null-terminated string containing the error message if setting of variable fails.

Definition at line 512 of file arts_api.cc.

References InteractiveWorkspace::initialize_variable(), VariableValueStruct::ptr, InteractiveWorkspace::set_agenda_variable(), and global_data::wsv_group_names.