### Environment Setup for Partial Get Plugin

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/partial_get_plugin.md

Sets environment variables to enable and locate the Partial Get Plugin for AL5. `IMAS_AL_ENABLE_PLUGINS` must be TRUE to activate plugin support, and `IMAS_AL_PLUGINS` should point to the directory containing the compiled plugin shared library.

```bash
export IMAS_AL_ENABLE_PLUGINS=TRUE
export IMAS_AL_PLUGINS=$HOME/AL_repos/al-cpp/build/_deps/al-plugins-build/
```

--------------------------------

### Using partialGet with C++

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/plugins.md

Demonstrates how to use the partialGet function in C++. This example shows the basic structure for retrieving data using the plugin, assuming necessary headers and library linkages are in place.

```cpp
#include <iostream>
#include "al5_plugin.h"

int main() {
    // Assuming al5_plugin_init() and other setup functions are called prior
    std::string query = "SELECT id, name FROM users WHERE status = 'active'";
    std::vector<std::string> fields = {"id", "name"};

    // Placeholder for the actual partialGet function call
    // The exact signature and return type will depend on the plugin's implementation.
    // Example: auto result = partialGet(query, fields);

    std::cout << "Executing partialGet query: " << query << std::endl;
    // Process the result here

    return 0;
}
```

--------------------------------

### C++ Example: Using partialGet for Data Filtering

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/partial_get_plugin.md

Demonstrates how to use the `partialGet` function in C++ to retrieve specific data from an `core_profiles` IDS instance. It defines 'includes' and 'excludes' query strings and applies them to populate the IDS object.

```cpp
// Define include and exclude queries
std::string includes = "ids_properties;profiles_1d(1:5:2)/ion(1:4:2)";
std::string excludes = "";

IDS::core_profiles cp = data_entry._core_profiles; // Declare the IDS instance
cp.partialGet(includes, excludes);
```

--------------------------------

### Build Documentation Examples with CMake

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/code_samples/tutorial/CMakeLists.txt

Configures the CMake build system to create an executable for documentation examples. It specifies the C++ language standard, sets a flag for POSIX threads, defines the main executable target, lists its source files, and links necessary libraries.

```cmake
project( docExamples LANGUAGES CXX )

set(THREADS_PREFER_PTHREAD_FLAG ON)

# Build Documentation Examples 
################################################################################
add_executable( main example_001_open_database.cpp example_002_fill_data_in_ids.cpp example_003_write_data_into_entry.cpp example_004_read_data_from_entry.cpp test_new_examples.cpp )
target_link_libraries( main PUBLIC al-cpp )
target_link_libraries( main PUBLIC -pthread )
```

--------------------------------

### Copy IDS Data via Memory Backend in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

This C++ example demonstrates copying IDS data by using a memory backend as an intermediary. The `put()` and `get()` methods are used to transfer data from a source IDS to the memory backend and then to a destination IDS, effectively creating a copy. This method is efficient for in-memory data transfers.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    // Create source IDS with data
    IdsNs::IDS::core_profiles source;
    source.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    source.time.resize(3);
    for (int i = 0; i < 3; i++) {
        source.time(i) = i;
    }

    // Create memory backend data entry
    IdsNs::IDS ids;
    ids.open("imas:memory?path=/", FORCE_CREATE_PULSE);

    // Associate both IDSs with the data entry
    source.setPulseCtx(ids.getPulseCtx());
    IdsNs::IDS::core_profiles dest;
    dest.setPulseCtx(ids.getPulseCtx());

    // Copy via put/get
    source.put();
    dest.get();

    // dest now contains a copy of source data
    std::cout << "Copied time points: " << dest.time.size() << std::endl;

    return 0;
}

```

--------------------------------

### IMAS C++ Plugin: Partial Get with Debug Mode

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/partial_get_plugin.md

This C++ code snippet demonstrates how to use the `partialGet` method of the IMAS C++ plugin with debug mode enabled. It shows the definition of include and exclude queries and how to retrieve core profiles data. Ensure the `IMAS_AL_PLUGINS` environment variable is set correctly and `partial_get_plugin.so` exists for the plugin to load.

```cpp
// Define include and exclude queries
std::string includes = "ids_properties;profiles_1d(1:5:2)/ion(1:4:2)";
std::string excludes = "";

IDS::core_profiles cp = data_entry._core_profiles; // Declare the IDS instance
cp.partialGet(includes, excludes, true); // debug is enabled
```

--------------------------------

### Generate and Install PkgConfig Files with CMake

Source: https://github.com/iterorganization/imas-cpp/blob/develop/CMakeLists.txt

This CMake snippet configures and installs pkg-config (.pc) files for the project's libraries. It uses 'configure_file' to process template files and then installs the generated .pc files into the 'lib/pkgconfig' directory.

```cmake
# Generate and install .pc files
configure_file( pkgconfig/al-cpp.pc.in al-cpp.pc @ONLY )
configure_file( pkgconfig/al-cpp-DD_VERSION.pc.in al-cpp-${DD_VERSION}.pc @ONLY )
configure_file( pkgconfig/al-identifiers-cpp.pc.in al-identifiers-cpp.pc @ONLY )
install( FILES
    ${CMAKE_CURRENT_BINARY_DIR}/al-cpp.pc
    ${CMAKE_CURRENT_BINARY_DIR}/al-cpp-${DD_VERSION}.pc
    ${CMAKE_CURRENT_BINARY_DIR}/al-identifiers-cpp.pc
  DESTINATION lib/pkgconfig
)
```

--------------------------------

### Compile C++ HLI with Plugin Support using CMake

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/partial_get_plugin.md

Compiles the C++ High-Level Interface (HLI) with plugin support enabled using CMake. The key flag `-DAL_PLUGINS=ON` is essential for enabling plugin functionality during the build process.

```bash
cmake -B build \
  -DAL_DOWNLOAD_DEPENDENCIES=OFF \
  -DAL_PLUGINS=ON \
  -DCMAKE_INSTALL_PREFIX=~/al-install/ \
  -DAL_DEVELOPMENT_LAYOUT=ON \
  -DCMAKE_BUILD_TYPE=Debug
```

--------------------------------

### Install Project Targets and Headers using CMake

Source: https://github.com/iterorganization/imas-cpp/blob/develop/CMakeLists.txt

This CMake code handles the installation of the built libraries and header files. It installs the 'al-cpp' and 'al-identifiers-cpp' targets, along with various header files into 'include/', 'include/cpp/', and 'include/ids/' directories, based on filtering generated headers.

```cmake
# Install
################################################################################

install( TARGETS al-cpp al-identifiers-cpp )

# Identifier headers
install( FILES ${IDENTIFIER_HEADERS} DESTINATION include/cpp )

# Headers installed in include/
set( BASE_HEADERS ${GENERATED_HEADERS} )
list( FILTER BASE_HEADERS EXCLUDE REGEX "src/ids" )
install( FILES ${BASE_HEADERS} DESTINATION include )
# Install non-generated headers
install( FILES src/ALDef.h src/IdsDef.h DESTINATION include )

# Headers installed in include/ids
set( IDS_HEADERS ${GENERATED_HEADERS} )
list( FILTER IDS_HEADERS INCLUDE REGEX "src/ids" )
install( FILES ${IDS_HEADERS} DESTINATION include/ids )
```

--------------------------------

### Extend Access Layer Functionality with C++ Plugin API

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

The IMAS C++ Access Layer supports a plugin system for extending functionality. This example shows how to register a plugin, bind it to specific IDS paths, and configure its parameters using functions like `al_register_plugin`, `al_bind_plugin`, and `al_setvalue_*_parameter_plugin`. Environment variables `IMAS_AL_ENABLE_PLUGINS` and `IMAS_AL_PLUGINS` must be set for plugins to work.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    // Environment setup required:
    // export IMAS_AL_ENABLE_PLUGINS=TRUE
    // export IMAS_AL_PLUGINS=/path/to/plugins/

    // Register a plugin (loads plugin_name_plugin.so from IMAS_AL_PLUGINS directory)
    al_status_t status = al_register_plugin("debug");
    if (status.code != 0) {
        std::cerr << "Failed to register plugin: " << status.message << std::endl;
        return 1;
    }

    // Bind plugin to specific paths (format: <ids_name>:<occurrence>/<path_in_ids>)
    al_bind_plugin("magnetics:0/ids_properties/version_put/access_layer", "debug");
    al_bind_plugin("magnetics:0/flux_loop", "debug");

    // Set plugin parameters
    al_setvalue_int_scalar_parameter_plugin("verbosity", 2, "debug");
    al_setvalue_double_scalar_parameter_plugin("threshold", 0.001, "debug");

    // Perform IDS operations - plugin intercepts bound paths
    IdsNs::IDS ids;
    ids.open("imas:hdf5?path=./testdb", FORCE_CREATE_PULSE);
    // ... IDS operations ...

    // Unbind and unregister when done
    al_unbind_plugin("magnetics:0/flux_loop", "debug");
    al_unregister_plugin("debug");

    ids.close();
    return 0;
}

```

--------------------------------

### Set Test Properties for Fixtures and Dependencies

Source: https://github.com/iterorganization/imas-cpp/blob/develop/examples/CMakeLists.txt

This snippet configures specific test properties, such as required fixtures and setup routines. It's used to manage dependencies between tests, ensuring that certain tests run only after their prerequisites are met.

```cmake
set_tests_properties(
  example-cpp-test_creation_date_plugin-with-plugins
  example-cpp-test_debug_plugin-with-plugins
  PROPERTIES FIXTURES_REQUIRED "example-cpp-test_magnetics_;example-cpp-test_magnetics_get"
)
set_tests_properties( example-cpp-test_magnetics_get
  PROPERTIES FIXTURES_SETUP example-cpp-test_magnetics_get
)
```

--------------------------------

### Conditional Subdirectory Inclusion for Tests and Examples in CMake

Source: https://github.com/iterorganization/imas-cpp/blob/develop/CMakeLists.txt

This CMake code conditionally includes subdirectories for tests and examples based on build options. If 'AL_TESTS' is enabled, it adds the 'tests/generator' subdirectory. If 'AL_EXAMPLES' is enabled, it adds 'examples' and 'doc/code_samples/tutorial'.

```cmake
# Tests
################################################################################

if( AL_TESTS )
  add_subdirectory( tests/generator )
endif()

if( AL_EXAMPLES )
  add_subdirectory( examples )
  add_subdirectory( doc/code_samples/tutorial )
endif()
```

--------------------------------

### Read Entire IDS with get() in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

The `get()` method reads a complete IDS with all time slices from the database. It can read the entire IDS or a specific occurrence. Ensure the IDS object is opened before calling `get()`.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    // Open existing data entry
    IdsNs::IDS ids;
    int status = ids.open("imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3", OPEN_PULSE);

    if (status != 0) {
        std::cerr << "Failed to open data entry" << std::endl;
        return 1;
    }

    // Read core_profiles IDS (occurrence 0)
    ids._core_profiles.get();

    // Access data
    std::cout << "Time mode: " << ids._core_profiles.ids_properties.homogeneous_time << std::endl;
    std::cout << "Time points: " << ids._core_profiles.time.size() << std::endl;

    for (int i = 0; i < ids._core_profiles.time.size(); i++) {
        std::cout << "t=" << ids._core_profiles.time(i) << std::endl;
    }

    // Read specific occurrence
    ids._core_profiles.get(1);  // Reads occurrence 1, overwrites current data

    // Check if IDS contains data
    if (ids._equilibrium.isDefined()) {
        ids._equilibrium.get();
        std::cout << "R0: " << ids._equilibrium.vacuum_toroidal_field.r0 << std::endl;
    }

    ids.close();
    return 0;
}
```

--------------------------------

### C++ HLI API for Partial Data Retrieval

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/partial_get_plugin.md

Provides C++ HLI API functions for retrieving partial data from an IDS based on user-defined queries. The `partialGet` function populates an IDS instance with data filtered by 'includes' and 'excludes' strings, with an optional 'debug' flag for query debugging.

```cpp
int partialGet(const std::string &includes, const std::string &excludes, bool debug=false);
int partialGet(int occ, const std::string &includes, const std::string &excludes, bool debug=false);
```

--------------------------------

### Create DBEntry (Legacy Mode) in C++

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/examples/001_1_create_db_entry_legacy.md

This C++ code snippet demonstrates how to create a DBEntry object using the legacy mode. It assumes necessary headers and libraries are included. The function initializes a DBEntry instance without relying on URI-based opening.

```cpp
#include <iostream>
#include "../imas_api/imas_api.h"

int main() {
    // This example focuses on creating DBEntry using legacy mode method
    DBEntry entry;
    entry.create("my_legacy_db");

    std::cout << "DBEntry created in legacy mode: " << entry.get_name() << std::endl;

    // This example focuses on opening DBEntry using URI
    return 0;
}
```

--------------------------------

### Open DBEntry using AL5 URI with Legacy Parameters (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/examples/001_2_open_URI_legacy.md

This C++ code snippet illustrates the process of opening a DBEntry by constructing and utilizing an AL5 URI with legacy parameters. It highlights the necessary includes and the function call for database entry opening.

```cpp
#include <iostream>
#include <string>
#include <vector>

// Assuming necessary headers for DBEntry and AL5 URI handling are included
// For example:
// #include "al5_uri.h"
// #include "dbentry.h"

int main() {
    // Example legacy parameters
    std::string legacy_param1 = "param1=value1";
    std::string legacy_param2 = "param2=value2";

    // Constructing the AL5 URI with legacy parameters
    std::string uri_string = "al5://database/entry_name?" + legacy_param1 + "&" + legacy_param2;

    // Assuming a function to open DBEntry exists
    // DBEntry db_entry = openDBEntry(uri_string);

    // Placeholder for actual DBEntry opening logic
    std::cout << "Attempting to open DBEntry with URI: " << uri_string << std::endl;
    // if (db_entry.isOpen()) {
    //     std::cout << "DBEntry opened successfully." << std::endl;
    // } else {
    //     std::cerr << "Failed to open DBEntry." << std::endl;
    // }

    return 0;
}
```

--------------------------------

### Build URI from Legacy Parameters (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_dbentry.md

Constructs a URI string using legacy parameters including backend ID, pulse, run, user, tokamak, version, and options. This function is useful for migrating or interfacing with systems that use older parameter formats. It requires the ALClasses.h header and the std namespace.

```cpp
#include "ALClasses.h"
#include <string>
#include <iostream>

using namespace IdsNs;

int main(int argc, char *argv[])
{
  al_status_t al_status;

  int pulse = 54;
  int run = 1234;

  std::string uri;
  std::string user = "public";
  std::string database = "test";
  std::string version = "3";
  std::string options = "";

  al_status = al_build_uri_from_legacy_parameters(MDSPLUS_BACKEND, pulse, run, user, database, version, options, uri);
  std::cout << al_status.code;

  return 0;
}
```

--------------------------------

### Build URI from Legacy Parameters in C++

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_dbentry.md

The al_build_uri_from_legacy_parameters function constructs a URI string using legacy parameters such as backend ID, pulse, run, user, tokamak, version, and options. It returns an al_status_t structure indicating success or failure. The generated URI is returned via a char pointer.

```cpp
#include "ALClasses.h"
#include <string>
using namespace IdsNs;

int main(int argc, char *argv[])
{
  al_status_t al_status;

  int pulse = 54;
  int run = 1234;

  char* uri;
  char* user = "public";
  char* database = "test";
  char* version = "3";
  char* options = "";

  al_status = al_build_uri_from_legacy_parameters(MDSPLUS_BACKEND, pulse, run, user, database, version, options, &uri);
  std::cout << al_status.code;

  return 0; 
}
```

--------------------------------

### IDS Get API

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_ids.md

Retrieves the entire contents of an IDS object from the database.

```APIDOC
## GET /get

### Description
Reads the entire contents of an IDS object, including all its time slices, from the database into memory. Empty fields will be populated with default values.

### Method
GET

### Endpoint
/get

### Parameters
#### Query Parameters
- **occurrence** (int) - Optional - Specifies which occurrence of the IDS to read. Defaults to 0.

### Response
#### Success Response (200)
- **status_code** (int) - 0 on success, <0 on failure.

#### Response Example
```json
{
  "status_code": 0
}
```
```

--------------------------------

### Compile C++ Access Layer Program using g++ and pkg-config

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/using_al.md

This bash command shows how to compile a C++ program that uses the Access Layer. It utilizes g++ as the compiler and `pkg-config --libs --cflags al-cpp` to automatically fetch the necessary compiler and linker flags for the 'al-cpp' library. The `-pthread` flag is also included for thread support.

```bash
g++ imas_hello_world.cpp `pkg-config --libs --cflags al-cpp` -pthread -o imas_hello_world

```

--------------------------------

### IDS Get Slice API

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_ids.md

Retrieves a specific time slice of an IDS object from the database.

```APIDOC
## GET /getSlice

### Description
Retrieves a specific time slice of an IDS object from the database. This is a variant of `Ids::getSlice(int, double, char)` with `occurrence` set to 0.

### Method
GET

### Endpoint
/getSlice

### Parameters
#### Query Parameters
- **inTime** (double) - Required - The time at which to retrieve the data slice.
- **interpolMode** (char) - Required - The interpolation mode to use for retrieving the data slice.

### Response
#### Success Response (200)
This endpoint's success response details are not explicitly provided in the documentation, but it is expected to return the requested data slice or a status code.

#### Response Example
(Example response not provided in documentation)
```

--------------------------------

### Read Specific Time Slice of IDS (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_ids.md

Reads a specific time slice of an IDS object from the database into memory. This method is similar to `get()` but allows specifying a time and interpolation mode. If the occurrence is not specified, it defaults to 0.

```cpp
int getSlice(double inTime, char interpolMode);
// Overload for occurrence = 0:
int getSlice(int, double inTime, char interpolMode);

// Example:
// Usage would involve calling getSlice with specific time and interpolation mode.
```

--------------------------------

### Open Data Entry using IDS Class in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

Demonstrates how to open and manage data entries using the `IdsNs::IDS` class in C++. It shows multiple methods for connecting to data storage, including recommended URI-based connections and a deprecated legacy parameter-based approach. The code also illustrates how to retrieve a pulse context and close the connection.

```cpp
#include "ALClasses.h"
#include <string>

using namespace IdsNs;

int main() {
    // Method 1: Open data entry using URI (recommended)
    IdsNs::IDS ids;
    int status = ids.open("imas:hdf5?path=./mydata", FORCE_CREATE_PULSE);
    // Available modes: OPEN_PULSE, CREATE_PULSE, FORCE_CREATE_PULSE, FORCE_OPEN_PULSE

    // Method 2: Open using URI with full parameters
    std::string uri = "imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3";
    status = ids.open(uri.c_str(), OPEN_PULSE);

    // Method 3: Legacy mode (deprecated)
    IdsNs::IDS ids_legacy(1, 10, 0, 0);  // pulse=1, run=10
    ids_legacy.setBackend(HDF5_BACKEND);
    ids_legacy.createEnv("username", "testdb", "3");  // user, database, dd_version

    // Get pulse context for IDS operations
    int ctx = ids.getPulseCtx();

    ids.close();
    return 0;
}
```

--------------------------------

### Set Pulse Context for Database Operations (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_ids.md

Sets the pulse context ID for database operations such as get(), getSlice(), put(), and putSlice(). The pulse context is obtained through specific means, likely related to database access or session management.

```cpp
void setPulseCtx(int pulseCtx);

// Example:
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {
    IdsNs::IDS ids;
    ids.open("imas:hdf5?path=my-data", FORCE_CREATE_PULSE);

    IdsNs::IDS::pf_active pf_active;
    pf_active.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    // ... fill pf_active ...

    pf_active.setPulseCtx(ids.getPulseCtx());
    pf_active.put();
    pf_active.put(1);

    return 0;
}
```

--------------------------------

### Create and Populate IDS in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

Demonstrates the creation and population of various IDS types, including core_profiles, edge_profiles, and gyrokinetics_local. It highlights the mandatory `ids_properties.homogeneous_time` field, array resizing, and handling multi-dimensional arrays.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    // Create a core_profiles IDS
    IdsNs::IDS::core_profiles core_profiles;

    // Set mandatory time mode field (required for all IDS)
    // Options: IDS_TIME_MODE_HETEROGENEOUS (0), IDS_TIME_MODE_HOMOGENEOUS (1), IDS_TIME_MODE_INDEPENDENT (2)
    core_profiles.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;

    // Allocate and fill time array (required for homogeneous time mode)
    core_profiles.time.resize(3);
    for (int i = 0; i < 3; i++) {
        core_profiles.time(i) = i * 0.1;  // t = 0.0, 0.1, 0.2
    }

    // Fill time-dependent data (size must match time array)
    core_profiles.global_quantities.ip.resize(3);
    for (int i = 0; i < 3; i++) {
        core_profiles.global_quantities.ip(i) = 1.0e6 + i * 1000;
    }

    // Working with Arrays of Structures (AoS)
    IdsNs::IDS::edge_profiles edge_profiles;
    edge_profiles.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    edge_profiles.grid_ggd.resize(2);  // Must resize before accessing elements
    edge_profiles.grid_ggd(0).identifier.name = "Grid 1";
    edge_profiles.grid_ggd(1).identifier.name = "Grid 2";

    // Resize and preserve existing data
    edge_profiles.grid_ggd.resizeAndPreserve(3);
    edge_profiles.grid_ggd(2).identifier.name = "Grid 3";

    // Multi-dimensional arrays
    IdsNs::IDS::gyrokinetics_local gyro;
    gyro.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    gyro.non_linear.fields_zonal_2d.phi_potential_perturbed_norm.resize(3, 3);
    for (int x = 0; x < 3; x++) {
        for (int y = 0; y < 3; y++) {
            gyro.non_linear.fields_zonal_2d.phi_potential_perturbed_norm(x, y) = x + y;
        }
    }

    // Check if IDS is defined
    bool defined = core_profiles.isDefined();  // true if homogeneous_time is set

    return 0;
}

```

--------------------------------

### Define and Configure al-identifiers-cpp Library Target in CMake

Source: https://github.com/iterorganization/imas-cpp/blob/develop/CMakeLists.txt

This CMake snippet defines the 'al-identifiers-cpp' library target, which is built from the generated identifier sources. It specifies include directories for both build and installation contexts, ensuring generated headers are accessible.

```cmake
add_library( al-identifiers-cpp ${IDENTIFIER_SOURCES} )
target_include_directories( al-identifiers-cpp PUBLIC
  $<BUILD_INTERFACE:${IDENTIFIER_SRC_DIR}>
  $<INSTALL_INTERFACE:include>  # <prefix>/include
)
```

--------------------------------

### Define C++ Test Executables and Link Libraries

Source: https://github.com/iterorganization/imas-cpp/blob/develop/examples/CMakeLists.txt

This snippet defines C++ executable targets for each test case and links them with the 'al-cpp' and 'al-identifiers-cpp' libraries. It also adds these targets as dependencies to a master 'example-cpp-all' target.

```cmake
add_executable( ${TEST_NAME} ${TEST}.cpp )
target_link_libraries( ${TEST_NAME} al-cpp al-identifiers-cpp)
add_dependencies( example-cpp-all ${TEST_NAME} )
```

--------------------------------

### Partial Get IDS Data (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_ids.md

Reads partial contents of an IDS into memory based on include and exclude queries. It fetches data where paths match include queries and are not excluded. Dependencies include ALClasses.h and iostream. Returns a status code: 0 for success, <0 for failure.

```cpp
#include "ALClasses.h"
#include <iostream>

int main(int argc, char *argv[]) {

    // Create a new data entry
    IdsNs::IDS data_entry;
  
    // Open the database entry by providing an IMAS URI
    data_entry.open("imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3", OPEN_PULSE);

    // Define include and exclude queries
   std::string includes = "ids_properties;profiles_1d(1:5:2)/ion(1:4:2)";
   std::string excludes = "";

   data_entry._core_profiles.partialGet(includes, excludes);

   return 0;
}
```

--------------------------------

### Version Constants

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_constants.md

Functions and variables for retrieving version information of the IMAS C++ library and its components.

```APIDOC
## Version constants

### const char *getALVersion()

Get the Access Layer low-level version.
Returns the version (C) string of the low-level component of the Access Layer, for example `"5.1.0"`.

### std::string al_cpp_version

Get the version string of the C++ Access Layer library, for example `"5.1.0"`.

### int al_cpp_major_version

Get the major version of the C++ Access Layer library, for example `5`.

### int al_cpp_minor_version

Get the minor version of the C++ Access Layer library, for example `1`.

### int al_cpp_patch_version

Get the patch version of the C++ Access Layer library, for example `0`.

### std::string al_dd_version

Get the version string of the Data Dictionary definitions that are used, for example `"3.39.0"`.

### int al_dd_major_version

Get the major version of the Data Dictionary definitions that are used, for example `3`.

### int al_dd_minor_version

Get the minor version of the Data Dictionary definitions that are used, for example `39`.

### int al_dd_patch_version

Get the patch version of the Data Dictionary definitions that are used, for example `0`.
```

--------------------------------

### Validate IDS Data Consistency with C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

The `validate()` method in C++ checks if IDS data adheres to Data Dictionary requirements. It throws a `ValidationException` if inconsistencies are found, such as missing coordinate arrays for 2D data. The example demonstrates how to fix validation errors by providing the necessary coordinate arrays.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    IdsNs::IDS::gyrokinetics_local gyro;
    gyro.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;

    // Fill 2D array without setting coordinate arrays (will fail validation)
    gyro.non_linear.fields_zonal_2d.phi_potential_perturbed_norm.resize(3, 3);
    for (int x = 0; x < 3; x++) {
        for (int y = 0; y < 3; y++) {
            gyro.non_linear.fields_zonal_2d.phi_potential_perturbed_norm(x, y) = x + y;
        }
    }

    try {
        gyro.validate();
        std::cout << "Validation passed" << std::endl;
    } catch (IdsNs::ValidationException& e) {
        std::cout << "Validation failed: " << e.what() << std::endl;
    }

    // Fix validation by setting coordinate arrays with matching dimensions
    gyro.non_linear.radial_wavevector_norm.resize(3);  // 1st dimension coordinate
    gyro.non_linear.time_norm.resize(3);               // 2nd dimension coordinate
    for (int i = 0; i < 3; i++) {
        gyro.non_linear.radial_wavevector_norm(i) = i * 0.1;
        gyro.non_linear.time_norm(i) = i;
    }

    try {
        gyro.validate();
        std::cout << "Validation passed after fix" << std::endl;
    } catch (IdsNs::ValidationException& e) {
        std::cout << "Validation still failed: " << e.what() << std::endl;
    }

    return 0;
}

```

--------------------------------

### Backend Identifiers

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_constants.md

Enumeration of available backend storage identifiers.

```APIDOC
## Backend identifiers

### enum BACKEND

### enumerator NO_BACKEND

### enumerator ASCII_BACKEND

ASCII backend

### enumerator MDSPLUS_BACKEND

MDSPLUS backend

### enumerator HDF5_BACKEND

HDF5 backend

### enumerator MEMORY_BACKEND

MEMORY backend

### enumerator UDA_BACKEND

UDA backend
```

--------------------------------

### Partial Get IDS Data (Occurrence 0) (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_ids.md

A variant of the partialGet function that defaults the occurrence parameter to 0. It retrieves partial IDS data based on include and exclude queries, similar to the main partialGet function. Dependencies include ALClasses.h and iostream. Returns a status code: 0 for success, <0 for failure.

```cpp
// This function signature is provided for reference and implies functionality similar to the main partialGet.
// Specific code example for this overload is not provided in the source text, but it would follow the pattern of the main partialGet.
// Example usage would involve calling: data_entry._core_profiles.partialGet(includes, excludes);
```

--------------------------------

### Print Access Layer Version Info in C++

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/using_al.md

This C++ code snippet demonstrates how to include the Access Layer header files and use the IdsNs namespace to access functions and variables that provide version information for the low-level access layer, data dictionary, and C++ High-Level Interface (HLI). It requires the 'ALClasses.h' header and standard iostream library.

```c++
// Include the Access Layer
#include "ALClasses.h"
#include <iostream>

// The Access Layer declares types in the IdsNs namespace. For brevity of
// examples we will use it here, even though it is considered bad practice:
// https://stackoverflow.com/questions/1452721/why-is-using-namespace-std-considered-bad-practice
using namespace IdsNs;

int main(int argc, char *argv[]) {
    std::cout << "Hello world!" << std::endl;
    std::cout << "Access Layer version info:" << std::endl;
    std::cout << "  Low level version: " << getALVersion() << std::endl;
    std::cout << "  Data Dictionary version: " << al_dd_version << std::endl;
    std::cout << "  C++ HLI version: " << al_cpp_version << std::endl;

    return 0;
}

```

--------------------------------

### Write IDS to Database (put) in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

Explains how to write an entire IDS to a data entry using the `put()` method. It covers opening a data entry, creating and populating an equilibrium IDS, associating it with the data entry, and writing to default or specific occurrences.

```cpp
#include "ALClasses.h"
#include <iostream>
#include <vector>
#include <string>

using namespace IdsNs;

int main() {
    // Open data entry
    IdsNs::IDS ids;
    ids.open("imas:hdf5?path=./testdb", FORCE_CREATE_PULSE);

    // Create and populate equilibrium IDS
    IdsNs::IDS::equilibrium equilibrium;
    equilibrium.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    equilibrium.ids_properties.comment = "Test equilibrium data";

    equilibrium.time.resize(3);
    equilibrium.vacuum_toroidal_field.b0.resize(3);
    for (int i = 0; i < 3; i++) {
        equilibrium.time(i) = i + 1;
        equilibrium.vacuum_toroidal_field.b0(i) = 2.5 + 0.1 * i;
    }
    equilibrium.vacuum_toroidal_field.r0 = 6.2;

    // Associate IDS with data entry
    equilibrium.setPulseCtx(ids.getPulseCtx());

    // Write to default occurrence (0)
    equilibrium.put();

    // Write to specific occurrence
    equilibrium.vacuum_toroidal_field.r0 = 6.5;  // Modify data
    equilibrium.put(1);  // Store as occurrence 1

    // List all occurrences
    std::vector<std::string> comments;
    std::vector<int> occurrences;
    IdsNs::IDS::list_all_occurrences(
        ids.getPulseCtx(), "equilibrium", "ids_properties/comment",
        comments, occurrences);

    for (size_t i = 0; i < occurrences.size(); i++) {
        std::cout << "Occurrence " << occurrences[i] << ": " << comments[i] << std::endl;
    }

    ids.close();
    return 0;
}

```

--------------------------------

### Partial Data Retrieval with partialGet() in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

The `partialGet()` method selectively retrieves data based on include/exclude path queries, optimizing memory usage for large IDS structures. It requires environment variables `IMAS_AL_ENABLE_PLUGINS` and `IMAS_AL_PLUGINS` to be set. It supports basic and nested path queries, and can be used with a specific occurrence.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    // Environment setup required:
    // export IMAS_AL_ENABLE_PLUGINS=TRUE
    // export IMAS_AL_PLUGINS=/path/to/plugins/

    IdsNs::IDS ids;
    ids.open("imas:mdsplus?user=public;pulse=131024;run=41;database=ITER;version=3", OPEN_PULSE);

    // Query syntax examples:
    // - "ids_properties" - include entire structure
    // - "profiles_1d(1:3:1)" - indices 1, 2, 3
    // - "profiles_1d(:)" - all elements
    // - "profiles_1d(1:5:2)/ion(1:4:2)" - nested AoS selection

    // Basic partial get
    std::string includes = "ids_properties;profiles_1d(1:5:2)/ion(1:4:2)";
    std::string excludes = "";
    ids._core_profiles.partialGet(includes, excludes);

    // With debug output
    ids._core_profiles.partialGet(includes, excludes, true);

    // With specific occurrence
    ids._core_profiles.partialGet(1, includes, excludes);

    // Include multiple paths
    includes = "ids_properties;profiles_1d(:)/grid;time";
    excludes = "profiles_1d(:)/ion";  // Exclude ion data
    ids._core_profiles.partialGet(includes, excludes);

    ids.close();
    return 0;
}
```

--------------------------------

### Build IMAS URI from Legacy Parameters in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

Provides a utility function `al_build_uri_from_legacy_parameters` to construct IMAS URIs from traditional parameter sets in C++. This is useful for migrating older codebases to the modern URI-based API. The function takes backend type, pulse, run, user, database, version, and options as input and returns the generated URI.

```cpp
#include "ALClasses.h"
#include <string>
#include <iostream>

using namespace IdsNs;

int main() {
    al_status_t al_status;
    int pulse = 54;
    int run = 1234;
    std::string uri;
    std::string user = "public";
    std::string database = "test";
    std::string version = "3";
    std::string options = "";

    // Build URI from legacy parameters
    al_status = al_build_uri_from_legacy_parameters(
        MDSPLUS_BACKEND, pulse, run, user, database, version, options, uri);

    if (al_status.code == 0) {
        std::cout << "Generated URI: " << uri << std::endl;
        // Result: imas:mdsplus?user=public;pulse=54;run=1234;database=test;version=3
    }
    return 0;
}
```

--------------------------------

### Plugins API

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/index.md

API for managing and interacting with plugins within the IMAS framework. This includes registration, unregistration, binding, unbinding, and setting plugin parameters.

```APIDOC
## Plugins API

### Description
This section details the API for managing and interacting with plugins in the IMAS framework. It provides functions for registering, unregistering, binding, unbinding plugins, and for setting various types of parameters for these plugins.

### Methods

*   **al_register_plugin(const char* plugin_name)**: Registers a plugin with the given name.
*   **al_unregister_plugin(const char* plugin_name)**: Unregisters a plugin.
*   **al_bind_plugin(const char* plugin_name, const char* event_name)**: Binds a plugin to a specific event.
*   **al_unbind_plugin(const char* plugin_name, const char* event_name)**: Unbinds a plugin from an event.
*   **al_setvalue_parameter_plugin(const char* plugin_name, int parameter_id, int type, void* value, const char* unit)**: Sets a generic parameter value for a plugin.
*   **al_setvalue_int_scalar_parameter_plugin(const char* plugin_name, int parameter_id, const char* unit)**: Sets an integer scalar parameter value for a plugin.
*   **al_setvalue_double_scalar_parameter_plugin(const char* plugin_name, double value, const char* unit)**: Sets a double scalar parameter value for a plugin.
```

--------------------------------

### Data Entry Open/Create Modes

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_constants.md

Flags that control how data entries are opened or created.

```APIDOC
## Data entry open/create modes

### OPEN_PULSE

Opens the access to the data only if the Data Entry exists, returns error otherwise.

### FORCE_OPEN_PULSE

Opens access to the data, creates the Data Entry if it does not exists yet.

### CREATE_PULSE

Creates a new empty Data Entry (returns error if Data Entry already exists) and opens it at the same time.

### FORCE_CREATE_PULSE

Creates an empty Data Entry (overwrites if Data Entry already exists) and opens it at the same time.
```

--------------------------------

### Bind Access Layer Plugin to Path (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_plugin.md

Activates a registered Access Layer plugin on a specific data path. After activation, the plugin can modify data on the specified path during read, write, or update operations. Requires the field path and plugin name.

```cpp
al_status_t status = al_register_plugin("debug");
if (status.code != 0) {
    std::cerr << status.message << std::endl;
    exit(1);
}
al_bind_plugin("magnetics:0/ids_properties/version_put/access_layer", "debug");
al_bind_plugin("magnetics:0/flux_loop", "debug");
```

--------------------------------

### Generate TestSuite.cpp using xsltproc

Source: https://github.com/iterorganization/imas-cpp/blob/develop/tests/generator/CMakeLists.txt

This custom command generates the TestSuite.cpp file from TestSuite.xsl using the xsltproc executable. It defines string parameters for various backends and depends on the XSLT file and IDSDEF. The output is placed in the binary directory.

```cmake
add_custom_command(
  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/TestSuite.cpp
  # Generate with xsltproc
  COMMAND
    ${LIBXSLT_XSLTPROC_EXECUTABLE}
      --output TestSuite.cpp
      --stringparam test_memory_backend not-implemented
      --stringparam test_ascii_backend not-implemented
      --stringparam test_mdsplus_backend $<IF:$<BOOL:${AL_BACKEND_MDSPLUS}>,yes,no>
      --stringparam test_hdf5_backend not-implemented
      --stringparam test_uda_backend not-implemented
      ${CMAKE_CURRENT_SOURCE_DIR}/TestSuite.xsl
      ${IDSDEF}
  DEPENDS TestSuite.xsl ${IDSDEF}
  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
)
```

--------------------------------

### Register Access Layer Plugin (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_plugin.md

Registers an Access Layer plugin by its name. The plugin must be compiled and located in the directory specified by the IMAS_AL_PLUGINS environment variable. Returns an al_status_t indicating success or failure.

```cpp
al_status_t status = al_register_plugin("debug");
if (status.code != 0) {
    std::cerr << status.message << std::endl;
    exit(1);
}
```

--------------------------------

### Set Plugin Parameter Value (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/api_plugin.md

Sets a parameter value for a registered Access Layer plugin. This function requires the parameter name, data type, dimension, size, data pointer, and the plugin name. Refer to specific plugin documentation for parameter details.

```cpp
al_setvalue_parameter_plugin("parameter_name", datatype, dim, size, data, "pluginName");
```

--------------------------------

### CMake: Configure Project and Dependencies

Source: https://github.com/iterorganization/imas-cpp/blob/develop/CMakeLists.txt

Sets up the CMake build environment, defines project metadata, and includes necessary modules for compiler settings and common configurations. It also handles dependency finding for libraries like Blitz.

```cmake
cmake_minimum_required( VERSION 3.16 )

option( AL_DOWNLOAD_DEPENDENCIES "Automatically download assets from the AL git repository" ON )
set( AL_CORE_GIT_REPOSITORY "ssh://git@git.iter.org/imas/al-core.git" CACHE STRING "Git repository of AL-core" )
set( AL_CORE_VERSION "main" CACHE STRING "Git commit/tag/branch of AL-core" )

include(FetchContent)

if( DEFINED ENV{AL_COMMON_PATH} )
  set( AL_COMMON_PATH $ENV{AL_COMMON_PATH} )
else()
  if( ${AL_DOWNLOAD_DEPENDENCIES} )
    FetchContent_Declare(
      al-core
      GIT_REPOSITORY "${AL_CORE_GIT_REPOSITORY}"
      GIT_TAG "${AL_CORE_VERSION}"
    )
  else()
    FetchContent_Declare(
      al-core
      SOURCE_DIR      "${CMAKE_CURRENT_SOURCE_DIR}/../al-core"
    )
  endif()
  FetchContent_MakeAvailable( al-core )
  set( AL_COMMON_PATH "${al-core_SOURCE_DIR}/common" )
endif()
add_subdirectory( ${AL_COMMON_PATH} _common )

set( GIT_ARCHIVE_DESCRIBE [[$Format:%(describe)$]] )
include( ALDetermineVersion )
project( al-cpp
  VERSION ${VERSION}
  DESCRIPTION "C++ High Level Interface of the IMAS Access Layer"
  HOMEPAGE_URL "https://imas.iter.org/"
  LANGUAGES C CXX
)
if( NOT PROJECT_VERSION_TWEAK EQUAL 0 )
  message( "Building a development version of the Access Layer C++ HLI" )
endif()

include( ALSetCompilerFlags )
include( ALCommonConfig )
include( ALBuildDataDictionary )
include( ALCore )

if( AL_DOCS_ONLY )
  return()
endif()

find_package( PkgConfig )
pkg_check_modules( blitz REQUIRED IMPORTED_TARGET blitz )

```

--------------------------------

### Put Entire IDS into Entry (C++)

Source: https://github.com/iterorganization/imas-cpp/blob/develop/doc/examples/003_1_put_entire_ids.md

This C++ code snippet illustrates the process of inserting entire IDS into an entry and ensuring they pass validation checks. It is designed for use within the imas-cpp project.

```cpp
// This example focuses on putting IDS into entry and passing IDS validation
    // This example focuses on putting multiple slices of IDS into entry
```

--------------------------------

### Find LibXslt Dependency for xsltproc

Source: https://github.com/iterorganization/imas-cpp/blob/develop/tests/generator/CMakeLists.txt

This snippet demonstrates how to find the LibXslt package, specifically looking for the xsltproc executable. If not found, it will halt the build with an error message. This is crucial for the custom command that generates test source files.

```cmake
find_package( LibXslt QUIET )
if( NOT LIBXSLT_XSLTPROC_EXECUTABLE )
  message( FATAL_ERROR "Could not find xsltproc" )
endif()
```

--------------------------------

### Write Time Slices (putSlice) in C++

Source: https://context7.com/iterorganization/imas-cpp/llms.txt

Details the use of the `putSlice()` method for appending time-dependent data incrementally, suitable for streaming or real-time acquisition. It demonstrates initializing arrays for a single slice, simulating a time loop, and appending multiple slices at once.

```cpp
#include "ALClasses.h"

using namespace IdsNs;

int main() {
    IdsNs::IDS ids;
    ids.open("imas:hdf5?path=./streaming_data", FORCE_CREATE_PULSE);

    IdsNs::IDS::summary summary;
    summary.ids_properties.homogeneous_time = IDS_TIME_MODE_HOMOGENEOUS;
    summary.setPulseCtx(ids.getPulseCtx());

    // Initialize arrays for single time slice
    summary.time.resize(1);
    summary.global_quantities.ip.value.resize(1);

    // Simulate time integration loop
    double t = 0.0;
    double t_stop = 5.0;
    double dt = 1.0;

    while (t < t_stop) {
        // Set current time slice
        summary.time(0) = t;
        summary.global_quantities.ip.value(0) = 1.0e6 * (1.0 + 0.1 * t);

        // Append slice to database (time must be strictly increasing)
        summary.putSlice();
        t += dt;
    }

    // Put multiple slices at once
    summary.time.resize(3);
    summary.global_quantities.ip.value.resize(3);
    for (int i = 0; i < 3; i++) {
        summary.time(i) = 10.0 + i;
        summary.global_quantities.ip.value(i) = 2.0e6 + i * 1000;
    }
    summary.putSlice();

    ids.close();
    return 0;
}

```