ARTS  2.4.0(git:4fb77825)
arts_api.cc File Reference
#include "arts_api.h"
#include "agenda_class.h"
#include "arts.h"
#include "auto_md.h"
#include "auto_version.h"
#include "global_data.h"
#include "interactive_workspace.h"
#include "parameters.h"
#include "parser.h"
#include "workspace_ng.h"

Go to the source code of this file.

Functions

Index get_wsv_id (const char *)
 Get index of WSV. More...
 
void copy_output_and_input (ArrayOfIndex &output, ArrayOfIndex &input, unsigned long n_args_out, const long *args_out, unsigned long n_args_in, const long *args_in)
 
void include_path_push (const char *path)
 Add include path. More...
 
void include_path_pop ()
 Remove last include path. More...
 
void data_path_push (const char *path)
 Add data path. More...
 
void data_path_pop ()
 Remove last data path. More...
 
void initialize ()
 Initalize ARTS runtime. More...
 
void finalize ()
 Finalize ARTS runtime. More...
 
const char * get_error ()
 Get most recent error. More...
 
void set_basename (const char *name)
 Set the ARTS basename. More...
 
Agendaparse_agenda (const char *filename)
 Parse Controlfile. More...
 
Agendacreate_agenda (const char *name)
 Create Agenda. More...
 
void agenda_insert_set (InteractiveWorkspace *workspace, Agenda *a, long id, long group_id)
 Insert a set method into an agenda. More...
 
void agenda_insert_callback (Agenda *a, void(*f)(InteractiveWorkspace *))
 Insert callback into agenda. More...
 
void agenda_add_method (Agenda *a, const long id, unsigned long n_output_args, const long *output_args, unsigned long n_input_args, const long *input_args)
 
void agenda_append (Agenda *dst, const Agenda *src)
 Append agendas. More...
 
void agenda_clear (Agenda *a)
 Clear Agenda. More...
 
const char * execute_agenda (InteractiveWorkspace *workspace, const Agenda *a)
 Execute Agenda. More...
 
void destroy_agenda (Agenda *a)
 Destroy Agenda. More...
 
InteractiveWorkspacecreate_workspace (const Index verbosity, const Index agenda_verbosity)
 Create new workspace. More...
 
void destroy_workspace (InteractiveWorkspace *workspace)
 Destroy given workspace. More...
 
unsigned long get_number_of_groups ()
 Return number of WSV groups. More...
 
const char * get_group_name (int i)
 Get pointer to name of given group. More...
 
unsigned long get_number_of_methods ()
 Return number of WSMs. More...
 
MethodStruct get_method (Index i)
 Return MethodStruct describing method with index i. More...
 
const char * get_method_in (Index i, Index j)
 
const char * get_method_g_in (Index i, Index j)
 Get name of generic input argument. More...
 
const char * get_method_g_in_default (Index i, Index j)
 Get default value of generic input argument. More...
 
const char * get_method_out (Index i, Index j)
 
const char * get_method_g_out (Index i, Index j)
 Get name value of generic output argument. More...
 
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...
 
const char * method_print_doc (long id)
 Print method documentation. More...
 
long lookup_workspace_variable (const char *s)
 Lookup workspace variable by name. More...
 
unsigned long get_number_of_variables ()
 Number of defined WSVs. More...
 
VariableStruct get_variable (Index i)
 Get WSV by index. More...
 
VariableValueStruct get_variable_value (InteractiveWorkspace *workspace, Index id, Index group_id)
 Get value WSV in given workspace. More...
 
void * get_variable_data_pointer (InteractiveWorkspace *workspace, Index id)
 Get data pointer to the WSV variable. More...
 
CovarianceMatrixBlockStruct get_covariance_matrix_block (CovarianceMatrix *m, long block_index, bool inverse)
 Return block of covariance matrix. More...
 
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...
 
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...
 

Variables

Parameters parameters
 Holds the command line parameters. More...
 
Verbosity verbosity_at_launch
 The global message verbosity settings: More...
 
String out_basename
 The basename for the report file and for all other output files. More...
 
std::string string_buffer
 

Function Documentation

◆ add_variable()

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()

void agenda_add_method ( Agenda a,
const long  id,
unsigned long  n_output_args,
const long *  output_args,
unsigned long  n_input_args,
const long *  input_args 
)

Definition at line 157 of file arts_api.cc.

References copy_output_and_input(), and Agenda::push_back().

◆ agenda_append()

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()

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()

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()

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.

◆ copy_output_and_input()

void copy_output_and_input ( ArrayOfIndex output,
ArrayOfIndex input,
unsigned long  n_args_out,
const long *  args_out,
unsigned long  n_args_in,
const long *  args_in 
)

Definition at line 30 of file arts_api.cc.

Referenced by agenda_add_method(), and execute_workspace_method().

◆ create_agenda()

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()

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()

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()

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()

void destroy_agenda ( Agenda a)

Destroy Agenda.

Parameters
aPointer to the agenda.

Definition at line 186 of file arts_api.cc.

◆ destroy_workspace()

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()

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()

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()

void finalize ( )

Finalize ARTS runtime.

Deletes the error buffer.

Definition at line 62 of file arts_api.cc.

◆ get_covariance_matrix_block()

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()

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_group_name()

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()

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()

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()

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()

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_method_in()

const char* get_method_in ( Index  i,
Index  j 
)

Definition at line 242 of file arts_api.cc.

References global_data::md_data.

◆ get_method_out()

const char* get_method_out ( Index  i,
Index  j 
)

Definition at line 254 of file arts_api.cc.

References global_data::md_data.

◆ get_number_of_groups()

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()

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()

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()

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()

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()

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.

◆ get_wsv_id()

Index get_wsv_id ( const char *  name)

Get index of WSV.

Returns the index the Workspace of the given WSV.

Convenience function which can be called from within the debugger because it takes a plain char pointer instead of a String object as input.

Parameters
[in]nameWSV name
Returns
Index in Workspace
Author
Oliver Lemke

Definition at line 5771 of file workspace.cc.

◆ include_path_pop()

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()

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()

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()

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()

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()

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()

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()

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.

Variable Documentation

◆ out_basename

String out_basename
extern

The basename for the report file and for all other output files.

The files will have names like <basename>.rep (for the report file).

Definition at line 42 of file messages.cc.

Referenced by arts_exit(), arts_exit_with_error_message(), filename_ascii(), filename_xml(), filename_xml_with_index(), main(), nca_filename(), nca_filename_with_index(), and set_basename().

◆ parameters

◆ string_buffer

std::string string_buffer

◆ verbosity_at_launch

Verbosity verbosity_at_launch
extern

The global message verbosity settings:

Definition at line 34 of file messages.cc.

Referenced by main(), parse_agenda(), set_reporting_level(), and verbosityInit().