v0.8.0

⚠️ Breaking Changes ⚠️

Handling Data-dependent Configuration Parameters

We now support data-dependent configuration in a thread safe way; for example, a configuration parameter that depends on the run number may only be set once the run number is known, and the run number can only be determined by reading the data. The run number may change while reading through the data, therefore the configuration parameter must be occasionally reloaded on-the-fly, but this must be done in a thread-safe manner.

If you use action functions, keep reading this section for the required changes; otherwise, if you use Run functions, you may skip to the next section since you are not impacted by these changes.

Two algorithms are impacted by this change, both requiring their function PrepareEvent to be called for each event before calling their action functions:

// physics::InclusiveKinematics
concurrent_key_t PrepareEvent(int const runnum, double const beam_energy = -1) const;

// clas12::ZVertexFilter
concurrent_key_t PrepareEvent(int const runnum) const;

This function handles the loading of configuration parameters for a given run number (runnum); furthermore, physics::InclusiveKinematics may use the RCDB to get the beam energy (if beam_energy argument is -1), or the caller may supply their own beam energy if preferred or needed.

Their return value is type concurrent_key_t, an integer, is a "hash key" and must be passed to the action function so that the correct configuration parameters are used.

The action function clas12::ZVertexFilter::Filter now requires additional parameters, in addition to the key:

- bool Filter(double const zvertex) const;
+ bool Filter(double const zvertex, int const pid, int const status, concurrent_key_t const key) const;

• pid and status are additional properties from the particle bank row
• key is the return value of PrepareEvent

Similarly, the action function physics::InclusiveKinematics::ComputeFromLepton also now requires a key as its last parameter:

- InclusiveKinematicsVars ComputeFromLepton(vector_element_t const lepton_px, vector_element_t const lepton_py, vector_element_t const lepton_pz) const;
+ InclusiveKinematicsVars ComputeFromLepton(vector_element_t const lepton_px, vector_element_t const lepton_py, vector_element_t const lepton_pz, concurrent_key_t const key) const;

The following pull requests are related to the above changes:

• feat: thread-safe configuration reload functions by @c-dilks in #258
• ZVertexFilter: Added option for pids and validator by @rtysonCLAS12 in #242
• ZVertexFilter: Only cut on FD and CD particles by @rtysonCLAS12 in #246

Removal of LorentzTransformer Algorithm

One other breaking change is the removal of the LorentzTransformer algorithm. This algorithm was just an example, and is not particularly useful since it is difficult to generalize. Details:

• refactor!: remove LorentzTransformer example algorithm by @c-dilks in #286

⭐ Primary Changes ⭐

Updates

• Sector Finder: Support for charged & neutral particles, added action function and validator by @rtysonCLAS12 in #243
• feat: chameleon, a tool for language binding generation by @c-dilks in #250
  • we currently only use this to generate Fortran bindings
  • we plan to use this to also generate bindings and tests for other languages
  • Python bindings are still generated by cppyy
• feat: thread-safe configuration reload functions by @c-dilks in #258
  • this is the data-dependent configuration handling mentioned above
  • some algorithms action functions have changed with the addition of this feature (see above)
• feat: use RCDB to get the beam energy by @c-dilks in #256
• feat: set configuration files and directories for all algorithms in an AlgorithmSequence by @c-dilks in #297
  • this is a convenience feature, so that users do not have to set custom configuration
    files or directories for each algorithm in an AlgorithmSequence; instead they
    only need to do so once
• feat: set algorithm log levels from config yaml files by @c-dilks in #298
  • this allows the log level to be controlled from configuration yaml files, for convenience
  • example YAML syntax: log: trace

New Algorithms

• feat: dihadron kinematics creator by @c-dilks in #291
• feat: single-hadron SIDIS kinematics by @c-dilks in #295

🚧 Technical Changes 🚧

• fix: treat warnings as errors and fix them by @c-dilks in #239
• ci: repeat benchmarks and get average time by @c-dilks in #241
• style: meson formatting by @c-dilks in #247
• fix: const parameters of action functions by @c-dilks in #255
• fix(ci): brew errors Broken pipe @ io_writev by @c-dilks in #248
• fix(ci): no need for meson argument --cmake-prefix-path since we already set $CMAKE_PREFIX_PATH by @c-dilks in #252
• fix: add FD cut for pre-filter photons in PhotonGBTFilter validator by @c-dilks in #254
• fix: test minimum and latest ROOT versions by @c-dilks in #264
• build(chameleon): decrease minimum ruby version and test it by @c-dilks in #257
• build: decrease ROOT minimum version 6.28.12 -> 6.28.10 by @c-dilks in #266
• feat(build): dump the project options by @c-dilks in #265
• fix(chameleon): compatibility with Ruby 3.2 by @c-dilks in #269
• fix(ci): fallback to alternate ALA mirror by @c-dilks in #273
• fix(CI): mitigate GitHub API rate limit by @c-dilks in #276
• ci: HIPO 4.2.0 testing by @c-dilks in #270
• fix: workaround -Wstringop-overflow warnings from fmt by @c-dilks in #278
• ci: add workflow_dispatch trigger by @c-dilks in #280
• doc: simplify dependencies list by @c-dilks in #287
• fix: iguana_test commands' usage guide by @c-dilks in #292
• fix: handle wrapper arguments when sourcing this_iguana.sh by @c-dilks in #296
• feat: change Algorithm::GetBankIndex to a public method by @c-dilks in #299
• feat: add pindex to InclusiveKinematicsVars by @c-dilks in #301
• fix: pindex should be short by @c-dilks in #302
• feat: calculate PhPerp for SIDIS hadrons and dihadrons by @c-dilks in #304
• fix: disable coverage test until fixed by @c-dilks in #305
• feat: allow for SQLite DBMS for RCDB by @c-dilks in #288
• build: make RCDB DBMS support optional by @c-dilks in #307
• refactor: use hipo::getBanklistIndex to get bank indices by @c-dilks in #300
• fix(doc): action functions must use action_function docstring, and non-action functions must not by @c-dilks in #312

---

Full Changelog: v0.7.1...v0.8.0

v0.7.1

⭐ Primary Changes ⭐

New Algorithms

• Fiducial Filter by @Gregtom3 in #226

⚠️ Breaking Changes ⚠️

• doc!: organize and rename examples, and additional small fixes by @c-dilks in #235
  • all executable names now use underscores (_) instead of hyphens (-), e.g., iguana-test becomes iguana_test
  • example names are now of the format:

  iguana_ex_[LANGUAGE]_[NUMBER]_[NAME]
  

  where:
  • [LANGUAGE] is the programming language
  • [NUMBER] is the example number (optional), for ordering examples for new users
    • examples without [NUMBER] are for certain, possibly language-specific, use cases
  • [NAME] is a descriptive name for the example

🚧 Technical Changes 🚧

• doc: improve the example and user documentation by @c-dilks in #234
• feat: add more build and OS artifacts to .gitignore by @c-dilks in #233
• doc: Fortran string termination by @c-dilks in #230

Full Changelog: v0.7.0...v0.7.1

v0.7.0

⚠️ Breaking Changes ⚠️

• refactor!: organize algorithms in subdirectories by @c-dilks in #206

This requires users who include algorithm headers to adjust the file name, since all algorithm headers are now named Algorithm.h and are organized into subdirectories named by the algorithm. For example,

// BEFORE CHANGE:
#include <iguana/algorithms/clas12/MomentumCorrection.h>

// AFTER CHANGE:
#include <iguana/algorithms/clas12/MomentumCorrection/Algorithm.h>

⭐ Primary Changes ⭐

New Algorithms

• Forward Tagger Energy Correction Function by @asligonulacar in #85
• Photon Gradient Boosted Tree Filter by @Gregtom3 in #216

Features and Fixes

• doc: improve testing and validator documentation by @c-dilks in #217
• feat: add ROOT macro example by @c-dilks in #210
  • This allows for integration with clas12root
• fix: make installation relocatable by @c-dilks in #215
  • This introduces the environment variable $IGUANA_CONFIG_PATH, which may be used to set the configuration directory; see updated configuration documentation

🚧 Technical Changes 🚧

• build: remove modulefile generation by @c-dilks in #213
• build: improve install-cvmfs.sh, removing forces subdirectories by @c-dilks in #214
• doc: meson test --test-args may need escaped hyphens by @c-dilks in #218
• build: warn about algorithms which lack validators by @c-dilks in #219
• feat: action function FTEnergyCorrection::CorrectEnergy by @c-dilks in #220
• Dglazier patch 1 by @dglazier in #222
• doc: add algorithm full name to API documentation by @c-dilks in #223
• ci: re-enable ubsan, since meson 1.4.1 has been released by @c-dilks in #228

New Contributors

• @asligonulacar made their first contribution in #85
• @Gregtom3 made their first contribution in #216

Full Changelog: v0.6.0...v0.7.0

v0.6.0

Breaking Changes

• build!: organize build options by @c-dilks in #189
  • "Expert" build options are now prefixed by z_, to keep them separate
  • new option z_install_envfile
  • Some build options are renamed, to make them more clear:

examples        -> install_examples
require_ROOT    -> z_require_root
make_modulefile -> z_install_modulefile

Primary Changes

• feat: make SectorFinder a creator algorithm and a prerequisite for MomentumCorrection by @c-dilks in #179
• Added hipopy and iguana integration example. by @mfmceneaney in #199
• build: require hipo minimum version 4.1.0 by @c-dilks in #198
• fix: use hipo iterators for proper bank row filtering by @c-dilks in #152
• feat: support tcsh environmental setup by @c-dilks in #207

Technical Changes

• feat: release automation by @c-dilks in #177
• chore: auto format by @c-dilks in #178
• fix(ci): revert to latest meson version by @c-dilks in #185
• build: install license by @c-dilks in #187
• ci: use xrootd validation files by @c-dilks in #188
• fix: use smart pointers for Fortran binding's Algorithm instances by @c-dilks in #180
• ci: disable ubsan until meson 1.5 by @c-dilks in #190
• build: module file tagging by @c-dilks in #192
• fix: omit empty variables from pkg-config file generation by @c-dilks in #197
• fix: do not require a Fortran compiler if Fortran is unused by @c-dilks in #196
• fix: resolve-dependencies.py might find the wrong .pc file by @c-dilks in #203
• feat: benchmark algorithms by @c-dilks in #204
• ci: run validators on all available events by @c-dilks in #205
• Fix header guards for TypeDefs.h by @dglazier in #209
• fix: support csh as well as tcsh by @c-dilks in #211

New Contributors

• @mfmceneaney made their first contribution in #199
• @dglazier made their first contribution in #209

Full Changelog: v0.5.0...v0.6.0

v0.5.0

Primary Changes

• doc: improve project description and algorithms' documentation by @c-dilks in #149
• feat: example using HIPO dataframes by @c-dilks in #157
• build!: strip runpaths from installation by @c-dilks in #164
• feat: Fortran bindings by @c-dilks in #172

Technical Changes

• fix: add executable permission for group and other for Python examples by @c-dilks in #139
• doc: link to ifarm documentation by @c-dilks in #136
• feat: tell the user which algorithm(s) create new banks by @c-dilks in #140
• test: increase coverage by @c-dilks in #142
• ci: increase artifact rentention time by @c-dilks in #148
• style: qualifier alignment to east const by @c-dilks in #143
• perf: replace std::string const-type parameters with std::string_view by @c-dilks in #150
• ci: temporarly roll back to meson 1.3.2 by @c-dilks in #155
• fix: add hipo to library rpaths by @c-dilks in #158
• fix(ci): only install doxygen when needed by @c-dilks in #162
• test: limit the number of events for example tests by @c-dilks in #165
• fix: dataframe example should not build if libHipoDataFrame is not installed by @c-dilks in #171
• fix(ci): don't deploy for PRs from forks when ref == main by @c-dilks in #176

Full Changelog: v0.4.1...v0.5.0

v0.4.1

What's Changed

• build: revert static hipo link by @c-dilks in #132
• build: add native file for ifarm builds by @c-dilks in #133

Full Changelog: v0.4.0...v0.4.1

v0.4.0

Primary Changes

• fix(ci): test ROOT-dependent algorithms by @c-dilks in #122
• Sectors by @rtysonCLAS12 in #126
• feat: algorithm validators by @c-dilks in #123
• feat: calculate inclusive kinematics by @c-dilks in #128

Technical Changes

• feat: test examples with meson test by @c-dilks in #116
• feat: auto-formatting with clang-format by @c-dilks in #103
• chore: auto format by @c-dilks in #117
• fix(ci): force macOS iguana rebuilds to also re-link by @c-dilks in #118
• ci: cache test HIPO files and hipo build by @c-dilks in #121
• feat: generalize configuration file Node finding by @c-dilks in #120
• doc: improve class diagrams by @c-dilks in #129

Full Changelog: v0.3.0...v0.4.0

v0.3.0

Primary Changes

• Implementing Config Files by @rtysonCLAS12 in #91
• feat: test algorithms with sanitizers and coverage by @c-dilks in #106
• feat: CODEOWNERS by @c-dilks in #112
• feat: momentum corrections by @c-dilks in #104
• feat: optionally depend on ROOT, and use it for boosting in LorentzTransformer by @c-dilks in #109

Technical Changes

• ci: use Arch Linux container on Linux runners by @c-dilks in #96
• fix: move Lorentz vector types to iguana namespace in common header by @c-dilks in #87
• ci: build hipo and fmt with 4 threads by @c-dilks in #88
• ci: bump actions versions by @c-dilks in #92
• fix(ci): set number of threads correctly by @c-dilks in #90
• fix: allow config files to be loaded by absolute or relative paths by @c-dilks in #102
• build: static link hipo4 by @c-dilks in #74
• fix: don't assume .pc files are found in $PREFIX/lib/pkgconfig by @c-dilks in #108
• feat: generalize config file handling for Algorithm by @c-dilks in #105
• doc: link examples to front-page by @c-dilks in #114

New Contributors

• @rtysonCLAS12 made their first contribution in #91

Full Changelog: v0.2.0...v0.3.0

v0.2.0

What's Changed

• feat: auto-set version number from git tag by @c-dilks in #57
• feat: python bindings by @c-dilks in #58
• doc: use markdown emphasis types by @c-dilks in #61
• build: use pkg-config for hipo4 by @c-dilks in #60
• style: test-dependent-build.sh -> test-consumer-build.sh by @c-dilks in #63
• ci: use python virtual environment for python bindings by @c-dilks in #64
• feat: example processing bank rows by @c-dilks in #65
• feat: generate algorithm boilerplate with preprocessor macros by @c-dilks in #66
• feat: generate a template algorithm by @c-dilks in #67
• feat: set default buildtype to release, controllable in configure.py by @c-dilks in #68
• doc: recommend latest dependency tag rather than main branch by @c-dilks in #72
• fix: macOS rpath and dynamic library issues by @c-dilks in #73
• doc: runtime dependency resolution by @c-dilks in #78
• build!: replace configure.py with meson documentation by @c-dilks in #80
• fix: remove Start, Run, Stop preprocessor macros by @c-dilks in #82
• fix: combine Algorithm.h and AlgorithmFactory.h by @c-dilks in #83
• fix: remove unnecessary things from test algorithms by @c-dilks in #84
• ci: use main hipo fork and latest tag by @c-dilks in #81
• doc: remove nproc suggestion by @c-dilks in #86

Full Changelog: v0.1.0...v0.2.0

v0.1.0

Initial C++ prototype

What's Changed

• feat: add logging service by @c-dilks in #1
• feat: read a HIPO file by @c-dilks in #2
• ci: add build job by @c-dilks in #5
• fix: allow old fmt by avoiding fmt::underlying by @c-dilks in #6
• fix: override default install directories for rpath consistency by @c-dilks in #8
• ci: run test by @c-dilks in #7
• doc: design diagram and notes by @c-dilks in #11
• doc: dependency graph by @c-dilks in #12
• feat: add event builder filter algorithm by @c-dilks in #9
• refactor!: regress c++20 to c++17 by @c-dilks in #15
• refactor: rename Arbiter->Iguana and organize main.cc by @c-dilks in #16
• fix: pass banks by reference by @c-dilks in #17
• refactor: use vector of banks for algorithm I/O by @c-dilks in #18
• feat: expose public Filter function in EventBuilderFilter by @c-dilks in #19
• feat+build: improve algorithm configuration; colored log output; improve dependency resolution by @c-dilks in #20
• feat(build): build configuration script by @c-dilks in #24
• build: set minimum dependency versions by @c-dilks in #25
• doc: dependency build notes by @c-dilks in #26
• refactor!: remove Algorithm::CopyBankRow by @c-dilks in #27
• fix: python shebang python->python3 by @c-dilks in #30
• fix: regress hipo::bank::get to hipo::bank::get[TYPE] by @c-dilks in #31
• refactor: use hipo::banklist for mutation by @c-dilks in #32
• build: clarify which paths correspond to which dependencies by @c-dilks in #35
• doc: remove *Config classes from design notes by @c-dilks in #36
• fix: enforce const correctness by @c-dilks in #37
• doc: generate API documentation and require everything to be documented by @c-dilks in #28
• doc: Doxyfile -> doc/Doxyfile by @c-dilks in #40
• refactor: rename class Iguana -> AlgorithmSequence by @c-dilks in #41
• fix(build): re-run meson setup if it failed by @c-dilks in #42
• feat: log levels quiet and silent by @c-dilks in #43
• feat: use banklist to cache bank indices by @c-dilks in #44
• doc: use @see by @c-dilks in #45
• feat: Lorentz transformer algorithm by @c-dilks in #46
• feat: algorithm sequencing by @c-dilks in #47
• feat: set log level if option name is "log" by @c-dilks in #48
• feat: templated Add algorithm to sequence by @c-dilks in #49
• fix: templated algorithm accessor in AlgorithmSequence by @c-dilks in #50
• refactor: minimize example by @c-dilks in #51
• fix: small fixes by @c-dilks in #52
• refactor: AlgorithmSequence should be an Algorithm by @c-dilks in #53
• feat: factory pattern with self-registration for algorithm creation by @c-dilks in #54
• build: decouple examples from main project and test dependence by @c-dilks in #55
• fix: bump version by @c-dilks in #56

Full Changelog: https://github.com/JeffersonLab/iguana/commits/v0.1.0