diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 970fc90c..9648006f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -347,37 +347,37 @@ jobs: run: | mv iguana relocated source relocated/bin/this_iguana.sh --verbose # do not use --githubCI option, since we want this environment to be for only this step - relocated/bin/iguana-example-basic test_data.hipo ${{ env.num_events }} + relocated/bin/iguana_ex_cpp_00_run_functions test_data.hipo ${{ env.num_events }} mv relocated iguana ### set iguana environment, since the next steps will check the iguana installation - name: set iguana environment run: source iguana/bin/this_iguana.sh --verbose --githubCI ### test installed examples ###### cpp - - run: iguana-example-basic test_data.hipo ${{ env.num_events }} + - run: iguana_ex_cpp_00_run_functions test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'cpp' }} - - run: iguana-example-bank-rows test_data.hipo ${{ env.num_events }} + - run: iguana_ex_cpp_01_action_functions test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'cpp' }} - - run: iguana-example-dataframes test_data.hipo ${{ env.num_events }} + - run: iguana_ex_cpp_dataframes test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'cpp' }} - - run: iguana-example-config-files iguana/etc/iguana/examples + - run: iguana_ex_cpp_config_files iguana/etc/iguana/examples if: ${{ matrix.id == 'cpp' }} ###### python - - run: iguana-example-basic.py test_data.hipo ${{ env.num_events }} + - run: iguana_ex_python_00_run_functions.py test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'python' }} - - run: iguana-example-bank-rows.py test_data.hipo ${{ env.num_events }} + - run: iguana_ex_python_01_action_functions.py test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'python' }} - - run: iguana-example-hipopy.py test_data.hipo ${{ env.num_events }} + - run: iguana_ex_python_hipopy.py test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'python' }} ###### fortran - - run: iguana-example-fortran test_data.hipo ${{ env.num_events }} + - run: iguana_ex_fortran_01_action_functions test_data.hipo ${{ env.num_events }} if: ${{ matrix.id == 'fortran' }} ### test ROOT macro - - name: test iguana_example_ROOT_macro.C interpreted - run: root -b -q iguana_src/examples/iguana_example_ROOT_macro.C + - name: test iguana_ex_cpp_ROOT_macro.C interpreted + run: root -b -q iguana_src/examples/iguana_ex_cpp_ROOT_macro.C if: ${{ matrix.id == 'cpp' }} - - name: test iguana_example_ROOT_macro.C compiled - run: root -b -q iguana_src/examples/iguana_example_ROOT_macro.C+ + - name: test iguana_ex_cpp_ROOT_macro.C compiled + run: root -b -q iguana_src/examples/iguana_ex_cpp_ROOT_macro.C+ if: ${{ matrix.id == 'cpp' }} ### test consumers - name: consumer test make @@ -385,14 +385,14 @@ jobs: run: | make -C iguana_src/examples/build_with_make echo "========================================= TEST RUN =========================================" - iguana_src/examples/build_with_make/bin/iguana-example-basic test_data.hipo 10 + iguana_src/examples/build_with_make/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10 - name: consumer test meson if: ${{ matrix.id == 'cpp' }} run: | meson setup build_consumer_meson iguana_src/examples/build_with_meson --prefix=$(pwd)/install_consumer_meson meson install -C build_consumer_meson echo "========================================= TEST RUN =========================================" - install_consumer_meson/bin/iguana-example-basic test_data.hipo 10 + install_consumer_meson/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10 - name: consumer test cmake if: ${{ matrix.id == 'cpp' }} run: | @@ -400,7 +400,7 @@ jobs: cmake --build build_consumer_cmake cmake --install build_consumer_cmake echo "========================================= TEST RUN =========================================" - install_consumer_cmake/bin/iguana-example-basic test_data.hipo 10 + install_consumer_cmake/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10 ### upload artifacts - uses: actions/upload-artifact@v4 if: always() diff --git a/README.md b/README.md index 73b9ce20..3804be4e 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Iguana is not a framework for _reading_ data, rather it is a set of algorithms t #### Language Bindings 1. [Python](/bind/python/README.md) -1. [Fortran](https://jeffersonlab.github.io/iguana/doxygen/group__fortran__usage__guide.html) +1. [All others: see the Iguana User's guide](https://jeffersonlab.github.io/iguana/doxygen) ### For Developers 1. [Design Notes](doc/design.md) diff --git a/bind/python/README.md b/bind/python/README.md index 75dbc184..8e31bd93 100644 --- a/bind/python/README.md +++ b/bind/python/README.md @@ -36,6 +36,6 @@ For Python to be able to find and use these bindings, you need to set some envir ## Running the Examples -Example Python scripts are found in this directory as `iguana-example-*.py`; they will be installed in the `bin/` subdirectory. +Example Python scripts are found in this directory as `iguana_ex_*.py`; they will be installed in the `bin/` subdirectory. Most of them are analogous to the C++ examples, but some may be specific to the Python bindings. diff --git a/bind/python/iguana-example-basic.py b/bind/python/iguana_ex_python_00_run_functions.py similarity index 90% rename from bind/python/iguana-example-basic.py rename to bind/python/iguana_ex_python_00_run_functions.py index 60436d3f..f958303a 100755 --- a/bind/python/iguana-example-basic.py +++ b/bind/python/iguana_ex_python_00_run_functions.py @@ -2,9 +2,8 @@ """! @begin_doc_example{python} -@file iguana-example-basic.py -@brief Python version of `iguana-example-basic.cc` -@see `iguana-example-basic.cc` for more information +@file iguana_ex_python_00_run_functions.py +@brief Python version of `iguana_ex_cpp_00_run_functions.cc` (for more details, see this `.cc` file) @end_doc_example @doxygen_off """ diff --git a/bind/python/iguana-example-bank-rows.py b/bind/python/iguana_ex_python_01_action_functions.py similarity index 94% rename from bind/python/iguana-example-bank-rows.py rename to bind/python/iguana_ex_python_01_action_functions.py index b2750dea..39fa5f9d 100755 --- a/bind/python/iguana-example-bank-rows.py +++ b/bind/python/iguana_ex_python_01_action_functions.py @@ -2,9 +2,8 @@ """! @begin_doc_example{python} -@file iguana-example-bank-rows.py -@brief Python version of `iguana-example-bank-rows.cc` -@see `iguana-example-bank-rows.cc` for more information +@file iguana_ex_python_01_action_functions.py +@brief Python version of `iguana_ex_cpp_01_action_functions.cc` (for more details, see this `.cc` file) @end_doc_example @doxygen_off """ diff --git a/bind/python/iguana-example-hipopy.py b/bind/python/iguana_ex_python_hipopy.py similarity index 98% rename from bind/python/iguana-example-hipopy.py rename to bind/python/iguana_ex_python_hipopy.py index 74d2a346..3622434c 100755 --- a/bind/python/iguana-example-hipopy.py +++ b/bind/python/iguana_ex_python_hipopy.py @@ -2,7 +2,7 @@ """! @begin_doc_example{python} -@file iguana-example-hipopy.py +@file iguana_ex_python_hipopy.py @brief Python iguana example using HIPOPy: https://github.com/mfmceneaney/hipopy @end_doc_example @doxygen_off diff --git a/bind/python/meson.build b/bind/python/meson.build index 94094517..415017a5 100644 --- a/bind/python/meson.build +++ b/bind/python/meson.build @@ -7,9 +7,9 @@ install_subdir( if(get_option('install_examples')) python_examples = [ - 'iguana-example-basic.py', - 'iguana-example-bank-rows.py', - 'iguana-example-hipopy.py', + 'iguana_ex_python_00_run_functions.py', + 'iguana_ex_python_01_action_functions.py', + 'iguana_ex_python_hipopy.py', ] foreach example : python_examples install_data( diff --git a/doc/gen/Doxyfile b/doc/gen/Doxyfile index 10563eb5..098e9c92 100644 --- a/doc/gen/Doxyfile +++ b/doc/gen/Doxyfile @@ -1006,8 +1006,8 @@ INPUT_FILE_ENCODING = FILE_PATTERNS = *.dox \ *.h \ - iguana-example-*.cc \ - iguana-example-*.py \ + iguana_ex_*.cc \ + iguana_ex_*.py \ Bindings.cc \ *.f \ *.C diff --git a/doc/gen/examples.dox b/doc/gen/examples.dox index 24919980..70c7b9e8 100644 --- a/doc/gen/examples.dox +++ b/doc/gen/examples.dox @@ -13,9 +13,13 @@ Iguana usage examples, organized by language and use cases: Iguana usage examples in C++ See below for the list of examples. +- If this is your first time using Iguana, start with the numbered examples + first, proceeding in order; since the list below is alphabetized, you may + start from the top. +- Examples without a number are specific to this language, showing certain use cases @see If you use build automation tools, here is guidance on how to include and link to Iguana in your C++ project; -they each show how build `iguana-example-basic.cc`, which "consumes" Iguana and HIPO as dependencies: +they each show how build `iguana_ex_cpp_00_run_functions.cc`, which "consumes" Iguana and HIPO as dependencies: - [**Meson consumer example**](https://github.com/JeffersonLab/iguana/tree/main/examples/build_with_meson) - [**CMake consumer example**](https://github.com/JeffersonLab/iguana/tree/main/examples/build_with_cmake) - [**Makefile consumer example**](https://github.com/JeffersonLab/iguana/tree/main/examples/build_with_make) @@ -28,6 +32,10 @@ they each show how build `iguana-example-basic.cc`, which "consumes" Iguana and Iguana usage examples in Python The examples here are analogous to the C++ examples +- If this is your first time using Iguana, start with the numbered examples + first, proceeding in order; since the list below is alphabetized, you may + start from the top. +- Examples without a number are specific to this language, showing certain use cases @see @ref examples_cpp "C++ examples" */ diff --git a/doc/gen/mainpage.md b/doc/gen/mainpage.md index 28ca7957..7b5a5dc3 100644 --- a/doc/gen/mainpage.md +++ b/doc/gen/mainpage.md @@ -11,12 +11,13 @@ This documentation shows how to use the Iguana algorithms. For more documentation, see - [**Documentation Front Page**](https://github.com/JeffersonLab/iguana/blob/main/README.md) -## Example Analysis Code +## Example Code in C++, Python, and Fortran To see Iguana algorithms used in the context of analysis code, with **various languages** and **use cases**, see: - - \ref examples_frontpage "Examples of Analysis Code" +**NOTE:** If you're not familiar with Iguana, please read the sections below first. + ## Algorithms An Iguana algorithm is a function that maps input HIPO bank data to output data. The available algorithms are: @@ -35,7 +36,7 @@ The algorithm types are defined based on what they do to HIPO bank data: Most algorithms are configurable: - [**Algorithm Configuration Guide**](https://github.com/JeffersonLab/iguana/blob/main/doc/configuration.md) -## Common Functions: for HIPO C++ Users +### Algorithm Common Functions: for HIPO C++ Users All algorithms have the following functions, which may be used in analysis code that uses [**the HIPO C++ API**](https://github.com/gavalian/hipo); for @@ -47,7 +48,7 @@ analysis code that does not, skip to the **Action Functions** section. `iguana::Algorithm::Stop` Run after event processing -## Action Functions: for All Users +### Algorithm Action Functions: for All Users The action functions do the _real_ work of the algorithm, and are meant to be easily callable from _any_ analysis, even if HIPO banks are not directly used. @@ -76,3 +77,4 @@ Inputs and outputs are scalar or vector quantities. To maximize compatibility with user analysis code, these functions are overloaded, _e.g._, for every scalar function there is a corresponding vector function that calls it on each element of its input vectors. + diff --git a/doc/setup.md b/doc/setup.md index 74d1120d..55b5092c 100644 --- a/doc/setup.md +++ b/doc/setup.md @@ -9,7 +9,7 @@ ## 🟠 Dependencies -The following sections (🔶) list the dependencies and how to obtain them. +The following sections (🟩) list the dependencies and how to obtain them. > [!TIP] > It's generally better to use your a package manager to install most dependencies, _e.g._: @@ -24,7 +24,7 @@ The following sections (🔶) list the dependencies and how to obtain them. > git checkout 1.0.0 # checkout the tag '1.0.0' > ``` -### 🔶 `meson`: Build system used by Iguana +### 🟩 `meson`: Build system used by Iguana - Likely available in your package manager, but the latest version is preferred and may be installed with `pip`: ```bash @@ -32,17 +32,17 @@ python -m pip install meson ninja ``` This includes [`ninja`](https://ninja-build.org/), which `meson` will benefit from using. -### 🔶 `fmt`: C++ output formatting library +### 🟩 `fmt`: C++ output formatting library - Likely available in your package manager, likely as `fmt` or `libfmt` - If you need Python bindings on macOS, please install `fmt` with `brew install fmt` - If you compile it yourself on Linux, include the `cmake` option `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` to build the static library -### 🔶 `yaml-cpp`: YAML parser and emitter +### 🟩 `yaml-cpp`: YAML parser and emitter - Likely available in your package manager, likely as `yaml-cpp` -### 🔶 `hipo`: C++ HIPO API +### 🟩 `hipo`: C++ HIPO API - Use the `hipo` module on `ifarm`, or obtain and build it yourself - Example `cmake` commands: @@ -52,7 +52,7 @@ cmake --build build-hipo cmake --install build-hipo ``` -### 🔶 Optional: `ROOT`: Data analysis framework +### 🟩 Optional: `ROOT`: Data analysis framework - ROOT is an **optional** dependency: some algorithms and test code depends on ROOT, but if you do not have ROOT on your system, `iguana` will build everything _except_ ROOT-dependent code diff --git a/doc/testing.md b/doc/testing.md index 956f2453..08ddec4d 100644 --- a/doc/testing.md +++ b/doc/testing.md @@ -1,9 +1,9 @@ # Testing and Validating Algorithms There are 2 ways to run tests: -- `iguana-test`: an installed executable used for running single tests; this offers more control at the expense of +- `iguana_test`: an installed executable used for running single tests; this offers more control at the expense of being less user friendly -- `meson test`: user-friendly automation of `iguana-test` +- `meson test`: user-friendly automation of `iguana_test` > [!IMPORTANT] > Both of these assume you are currently in your **build directory**. @@ -14,21 +14,21 @@ There are 2 ways to run tests: > (CI), so if you are developing and you submit a pull requests, you may rely > on the CI logs to check if the tests were successful -## `iguana-test` +## `iguana_test` -`iguana-test` is found both in the installation's `bin/` directory and in your build directory, +`iguana_test` is found both in the installation's `bin/` directory and in your build directory, ```bash -src/iguana/tests/iguana-test # assuming your build directory layout is 'mirror' (the default) +src/iguana/tests/iguana_test # assuming your build directory layout is 'mirror' (the default) ``` -Run `iguana-test` for a usage guide: +Run `iguana_test` for a usage guide: ```bash -src/iguana/tests/iguana-test # usage guide -src/iguana/tests/iguana-test validator # usage of the 'validator' command -src/iguana/tests/iguana-test algorithm # usage of the 'algorithm' command +src/iguana/tests/iguana_test # usage guide +src/iguana/tests/iguana_test validator # usage of the 'validator' command +src/iguana/tests/iguana_test algorithm # usage of the 'algorithm' command ``` For example, ```bash -src/iguana/tests/iguana-test validator -f ../data.hipo -n 0 -a clas12::MomentumCorrectionValidator -o ../validator_output +src/iguana/tests/iguana_test validator -f ../data.hipo -n 0 -a clas12::MomentumCorrectionValidator -o ../validator_output ``` will run the validator `MomentumCorrectionValidator` using data from `../data.hipo` and write its output to `../validator_output/`. @@ -59,19 +59,19 @@ meson test validator-clas12-MyAlgorithm --verbose # run and show output (stdout ``` If you have not supplied the required arguments, in particular the input data file, the test will fail. For the `validator` and `algorithm` test suites, -`iguana-test validator` and `iguana-test algorithm` are the respective +`iguana_test validator` and `iguana_test algorithm` are the respective underlying test executable commands; you may pass arguments to them using the `--test-args` option; for example: ```bash meson test validator-clas12-MyAlgorithm --verbose --test-args '\-f ../my_hipo_file.hipo \-n 300 \-o ../validator_output' ``` -See above for `iguana-test` usage guidance. +See above for `iguana_test` usage guidance. > [!NOTE] > Note the usage of an escaped hyphen, `\-` instead of `-`; depending on your system, you may or may not need to use escaped hyphens in > `--test-args` arguments, otherwise you will see errors such as `argument --test-args: expected one argument`. -Alternatively to using `--test-args`, you may set _default_ `iguana-test` +Alternatively to using `--test-args`, you may set _default_ `iguana_test` arguments using Iguana **build options**: - The options that are relevant for tests are prefixed by `test_` - Set options using `meson configure` and re-running `meson install` diff --git a/examples/README.md b/examples/README.md index 9a7247ae..18e040d5 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,7 +4,7 @@ All of the examples (`*.cc`) in [this `examples/` directory](/examples) may be b option `install_examples` is set to `True`. They will be installed in the `bin/` subdirectory of your Iguana installation. Read the example code to understand how to use Iguana, or -- [View the Examples Documentation](https://jeffersonlab.github.io/iguana/doxygen/group__examples.html) +- [View the Iguana User's Guide](https://jeffersonlab.github.io/iguana/doxygen) If you would like to integrate Iguana into an existing analysis, you'll need to add Iguana as a dependency. The following subdirectories are diff --git a/examples/build_with_cmake/CMakeLists.txt b/examples/build_with_cmake/CMakeLists.txt index 372f0eff..add2d521 100644 --- a/examples/build_with_cmake/CMakeLists.txt +++ b/examples/build_with_cmake/CMakeLists.txt @@ -18,7 +18,7 @@ pkg_check_modules(hipo4 REQUIRED IMPORTED_TARGET hipo4) pkg_check_modules(iguana REQUIRED IMPORTED_TARGET iguana) # build and install the executable -set(EXAMPLE_BIN iguana-example-basic) +set(EXAMPLE_BIN iguana_ex_cpp_00_run_functions) add_executable(${EXAMPLE_BIN}) target_sources(${EXAMPLE_BIN} PRIVATE ${EXAMPLE_BIN}.cc) target_link_libraries(${EXAMPLE_BIN} PUBLIC PkgConfig::iguana PkgConfig::hipo4) diff --git a/examples/build_with_cmake/iguana-example-basic.cc b/examples/build_with_cmake/iguana-example-basic.cc deleted file mode 120000 index 00b70b98..00000000 --- a/examples/build_with_cmake/iguana-example-basic.cc +++ /dev/null @@ -1 +0,0 @@ -../iguana-example-basic.cc \ No newline at end of file diff --git a/examples/build_with_cmake/iguana_ex_cpp_00_run_functions.cc b/examples/build_with_cmake/iguana_ex_cpp_00_run_functions.cc new file mode 120000 index 00000000..92141268 --- /dev/null +++ b/examples/build_with_cmake/iguana_ex_cpp_00_run_functions.cc @@ -0,0 +1 @@ +../iguana_ex_cpp_00_run_functions.cc \ No newline at end of file diff --git a/examples/build_with_make/iguana-example-basic.cc b/examples/build_with_make/iguana-example-basic.cc deleted file mode 120000 index 00b70b98..00000000 --- a/examples/build_with_make/iguana-example-basic.cc +++ /dev/null @@ -1 +0,0 @@ -../iguana-example-basic.cc \ No newline at end of file diff --git a/examples/build_with_make/iguana_ex_cpp_00_run_functions.cc b/examples/build_with_make/iguana_ex_cpp_00_run_functions.cc new file mode 120000 index 00000000..92141268 --- /dev/null +++ b/examples/build_with_make/iguana_ex_cpp_00_run_functions.cc @@ -0,0 +1 @@ +../iguana_ex_cpp_00_run_functions.cc \ No newline at end of file diff --git a/examples/build_with_meson/iguana-example-basic.cc b/examples/build_with_meson/iguana-example-basic.cc deleted file mode 120000 index 00b70b98..00000000 --- a/examples/build_with_meson/iguana-example-basic.cc +++ /dev/null @@ -1 +0,0 @@ -../iguana-example-basic.cc \ No newline at end of file diff --git a/examples/build_with_meson/iguana_ex_cpp_00_run_functions.cc b/examples/build_with_meson/iguana_ex_cpp_00_run_functions.cc new file mode 120000 index 00000000..92141268 --- /dev/null +++ b/examples/build_with_meson/iguana_ex_cpp_00_run_functions.cc @@ -0,0 +1 @@ +../iguana_ex_cpp_00_run_functions.cc \ No newline at end of file diff --git a/examples/build_with_meson/meson.build b/examples/build_with_meson/meson.build index 17ea16bf..079ce5dc 100644 --- a/examples/build_with_meson/meson.build +++ b/examples/build_with_meson/meson.build @@ -11,7 +11,7 @@ hipo_dep = dependency('hipo4') iguana_dep = dependency('iguana') # build and install the executable -example_bin = 'iguana-example-basic' +example_bin = 'iguana_ex_cpp_00_run_functions' executable( example_bin, example_bin + '.cc', diff --git a/examples/iguana-example-basic.cc b/examples/iguana_ex_cpp_00_run_functions.cc similarity index 89% rename from examples/iguana-example-basic.cc rename to examples/iguana_ex_cpp_00_run_functions.cc index a90935dd..8444bf43 100644 --- a/examples/iguana-example-basic.cc +++ b/examples/iguana_ex_cpp_00_run_functions.cc @@ -1,10 +1,10 @@ /// @begin_doc_example{cpp} -/// @file iguana-example-basic.cc -/// @brief Example using full HIPO banks with Iguana This example requires the -/// user to have the C++ `hipo::bank` objects; see other examples if you do not have these banks in this format. +/// @file iguana_ex_cpp_00_run_functions.cc +/// @brief Example using **full HIPO banks** with Iguana algorithms' `Run` functions. This example requires the +/// user to have the C++ `hipo::bank` objects; see other examples if you do not have banks in this format. /// @par Usage /// ```bash -/// iguana-example-basic [HIPO_FILE] [NUM_EVENTS] +/// iguana_ex_cpp_00_run_functions [HIPO_FILE] [NUM_EVENTS] /// /// HIPO_FILE the HIPO file to analyze /// diff --git a/examples/iguana-example-bank-rows.cc b/examples/iguana_ex_cpp_01_action_functions.cc similarity index 96% rename from examples/iguana-example-bank-rows.cc rename to examples/iguana_ex_cpp_01_action_functions.cc index 8721c225..d334e54b 100644 --- a/examples/iguana-example-bank-rows.cc +++ b/examples/iguana_ex_cpp_01_action_functions.cc @@ -1,10 +1,10 @@ /// @begin_doc_example{cpp} -/// @file iguana-example-bank-rows.cc +/// @file iguana_ex_cpp_01_action_functions.cc /// @brief Example using Iguana action functions on data from bank rows. This is useful for /// users who do not have the `hipo::bank` objects, instead only having the numerical data from them. /// @par Usage /// ```bash -/// iguana-example-bank-rows [HIPO_FILE] [NUM_EVENTS] +/// iguana_ex_cpp_01_action_functions [HIPO_FILE] [NUM_EVENTS] /// /// HIPO_FILE the HIPO file to analyze /// diff --git a/examples/iguana_example_ROOT_macro.C b/examples/iguana_ex_cpp_ROOT_macro.C similarity index 67% rename from examples/iguana_example_ROOT_macro.C rename to examples/iguana_ex_cpp_ROOT_macro.C index 7adc1b41..b7b5af8d 100644 --- a/examples/iguana_example_ROOT_macro.C +++ b/examples/iguana_ex_cpp_ROOT_macro.C @@ -1,10 +1,10 @@ /// @begin_doc_example{cpp} -/// @file iguana_example_ROOT_macro.C +/// @file iguana_ex_cpp_ROOT_macro.C /// @brief Very simple example showing how to load and use an Iguana algorithm in a ROOT macro; this example /// only runs the algorithm and does not require any input data. /// @par Usage /// ```bash -/// root -b -q iguana_example_ROOT_macro.C +/// root -b -q iguana_ex_cpp_ROOT_macro.C /// ``` /// @end_doc_example @@ -12,18 +12,24 @@ #include /// example ROOT macro function -void iguana_example_ROOT_macro() { +void iguana_ex_cpp_ROOT_macro() { // load the iguana algorithms library gSystem->Load("libIguanaAlgorithms"); - // run the inclusive kinematics action function + // start the inclusive kinematics algorithm iguana::physics::InclusiveKinematics algo; algo.Start(); + + // run the inclusive kinematics action function for a scattered electron lepton momentum, + // and print out the resulting inclusive kinematics auto result = algo.ComputeFromLepton(0.3, 0.3, 5.0); std::cout << "kinematics:" << "\n Q2 = " << result.Q2 << "\n x = " << result.x << "\n W = " << result.W << std::endl; + + // stop the algorithm + algo.Stop(); } diff --git a/examples/iguana-example-config-files.cc b/examples/iguana_ex_cpp_config_files.cc similarity index 97% rename from examples/iguana-example-config-files.cc rename to examples/iguana_ex_cpp_config_files.cc index fb8df7bd..51f8948a 100644 --- a/examples/iguana-example-config-files.cc +++ b/examples/iguana_ex_cpp_config_files.cc @@ -2,7 +2,7 @@ #include /// @begin_doc_example{cpp} -/// @file iguana-example-config-files.cc +/// @file iguana_ex_cpp_config_files.cc /// @brief Example showing how to control algorithm configuration. /// /// Examples include: @@ -12,7 +12,7 @@ /// /// @par Usage /// ```bash -/// iguana-example-config-files [CONFIG_FILE_DIRECTORY] +/// iguana_ex_cpp_config_files [CONFIG_FILE_DIRECTORY] /// /// CONFIG_FILE_DIRECTORY a custom directory with config files /// (default = an example directory) diff --git a/examples/iguana-example-dataframes.cc b/examples/iguana_ex_cpp_dataframes.cc similarity index 96% rename from examples/iguana-example-dataframes.cc rename to examples/iguana_ex_cpp_dataframes.cc index 8d7a5d4e..7932d668 100644 --- a/examples/iguana-example-dataframes.cc +++ b/examples/iguana_ex_cpp_dataframes.cc @@ -1,9 +1,9 @@ /// @begin_doc_example{cpp} -/// @file iguana-example-dataframes.cc +/// @file iguana_ex_cpp_dataframes.cc /// @brief Example using HIPO data frames with Iguana. Requires ROOT. /// @par Usage /// ```bash -/// iguana-example-dataframes [HIPO_FILE] [NUM_EVENTS] [INTERACTIVE_MODE] +/// iguana_ex_cpp_dataframes [HIPO_FILE] [NUM_EVENTS] [INTERACTIVE_MODE] /// /// HIPO_FILE the HIPO file to analyze /// diff --git a/examples/iguana-example-fortran.f b/examples/iguana_ex_fortran_01_action_functions.f similarity index 98% rename from examples/iguana-example-fortran.f rename to examples/iguana_ex_fortran_01_action_functions.f index b52dee26..ae4e4164 100644 --- a/examples/iguana-example-fortran.f +++ b/examples/iguana_ex_fortran_01_action_functions.f @@ -1,13 +1,13 @@ !> @begin_doc_example{fortran} - !> @file iguana-example-fortran.f + !> @file iguana_ex_fortran_01_action_functions.f !> @brief Fortran example demonstrating how to read a HIPO file and use - !> its data with Iguana algorithms. + !> its data with Iguana algorithms' action functions. !> Run with no arguments to see the usage guide. !> @see @ref fortran_usage_guide for more guidance !> @end_doc_example !> !> Fortran example program - program iguana_example_fortran + program iguana_ex_fortran_01_action_functions use iso_c_binding implicit none diff --git a/examples/meson.build b/examples/meson.build index 65f6f6aa..185379f3 100644 --- a/examples/meson.build +++ b/examples/meson.build @@ -4,22 +4,22 @@ install_subdir('config', install_dir: example_config_files_prefix, strip_directo # example source information example_sources = { - 'iguana-example-basic': { - 'sources': [ 'iguana-example-basic.cc' ], + 'iguana_ex_cpp_00_run_functions': { + 'sources': [ 'iguana_ex_cpp_00_run_functions.cc' ], }, - 'iguana-example-bank-rows': { - 'sources': [ 'iguana-example-bank-rows.cc' ], + 'iguana_ex_cpp_01_action_functions': { + 'sources': [ 'iguana_ex_cpp_01_action_functions.cc' ], }, - 'iguana-example-dataframes': { - 'sources': [ 'iguana-example-dataframes.cc' ], + 'iguana_ex_cpp_dataframes': { + 'sources': [ 'iguana_ex_cpp_dataframes.cc' ], 'build_this': ROOT_dep.found() and hipo_dep_dataframes_found, }, - 'iguana-example-config-files': { - 'sources': [ 'iguana-example-config-files.cc' ], + 'iguana_ex_cpp_config_files': { + 'sources': [ 'iguana_ex_cpp_config_files.cc' ], 'test_args': [ get_option('prefix') / example_config_files_prefix ], }, - 'iguana-example-fortran': { - 'sources': [ 'iguana-example-fortran.f' ], + 'iguana_ex_fortran_01_action_functions': { + 'sources': [ 'iguana_ex_fortran_01_action_functions.f' ], 'build_this': get_option('bind_fortran') and ROOT_dep.found(), # depends on physics::InclusiveKinematics, which depends on ROOT }, } diff --git a/src/iguana/tests/iguana-test.cc b/src/iguana/tests/iguana_test.cc similarity index 100% rename from src/iguana/tests/iguana-test.cc rename to src/iguana/tests/iguana_test.cc diff --git a/src/iguana/tests/meson.build b/src/iguana/tests/meson.build index 7be85059..d525f5c4 100644 --- a/src/iguana/tests/meson.build +++ b/src/iguana/tests/meson.build @@ -1,4 +1,4 @@ -test_exe_name = 'iguana-test' +test_exe_name = 'iguana_test' test_exe_inc = include_directories('include') test_exe_links = [ project_libs, vdor_lib ] @@ -82,10 +82,10 @@ foreach algo : algo_dict endif endforeach -# test usage guide for each iguana-test command +# test usage guide for each iguana_test command foreach command : ['', 'unknown', 'algorithm', 'validator', 'unit', 'config'] test( - 'iguana-test-usage-guide' + (command=='' ? '' : '-' + command), + 'iguana_test-usage-guide' + (command=='' ? '' : '-' + command), test_exe, args: command=='' ? [] : [command], env: project_test_env,