v1.1.0

Summary

• Various updates to support Monte Carlo data in algorithms:
  • Algorithms which use REC::Particle now support other particle-type banks, in particular, MC::Particle
  • physics::InclusiveKinematics can now use MC::Lund and parent information to find the scattered electron; see its new configuration options
  • New algorithm clas12::MatchParticleProximity provides simple matching between two particle banks using smallest distance in $(\theta,\phi)$; for example, use this to match REC::Particle and MC::Particle for data which lack truth-matching banks (MC::GenMatch and MC::RecMatch)
  • Override the beam energy from RCDBReader, which is useful if your run number is 11 and you know the beam energy of your Monte Carlo sample
• Documentation is now generated for each version number release of Iguana
  • Use the documentation for the version that you are using
  • The upper-left corner of the Doxygen webpage tells you the version
  • The "LATEST" version is for the current main branch, which is always ahead of the latest version number release
  • See https://jeffersonlab.github.io/iguana/

What's Changed

🦎 Algorithm Updates

• feat: improve event-level filter for SIDIS kinematics by @c-dilks in #383
• feat: add initial electron vz cuts for RG-B by @c-dilks in #387
• feat: simple MC truth matching by proximity by @c-dilks in #394
• feat!: MC truth updates in InclusiveKinematics and generalize and rename proximity matching by @c-dilks in #404

⭐ General Updates

• feat: support MC particle banks for hipo::banklist users by @c-dilks in #395
• feat: allow for override of beam energy from RCDBReader by @c-dilks in #398
• build: use $RCDB_HOME if option rcdb:home unset by @c-dilks in #408

🐛 Bug Fixes

• fix(InclusiveKinematics): do not use particle bank filter before lepton finding by @c-dilks in #382
• fix: support banks with duplicated names in hipo::banklist by @c-dilks in #397
• fix: always reset created banks in Run functions by @c-dilks in #403
• fix: expand ~ to $HOME in file paths by @c-dilks in #407

📖 Documentation Updates

• feat: check algorithm docstrings, and describe custom event-filters in AlgorithmSequence by @c-dilks in #381
• doc: generate documentation webpage for each tag by @c-dilks in #386
• fix(doc): banklist documentation linking by @c-dilks in #399
• doc: improve documentation for accessing created banks by @c-dilks in #401

📦 Dependency Changes

• build(deps): bump actions/checkout from 4 to 5 by @dependabot[bot] in #389
• build(deps): bump actions/upload-pages-artifact from 3 to 4 by @dependabot[bot] in #390
• build(deps): bump actions/upload-artifact from 4 to 5 by @dependabot[bot] in #392
• build(deps): bump actions/download-artifact from 4 to 6 by @dependabot[bot] in #391
• fix: Update hipopy version. by @mfmceneaney in #393
• build(deps): bump actions/checkout from 5 to 6 by @dependabot[bot] in #405

🔧 Technical Changes

• fix: disable dataframe test for now by @c-dilks in #385
• feat: .git-blame-ignore-revs file by @c-dilks in #379
• feat: enable dependabot by @c-dilks in #388
• refactor!: remove SetParticleBankName in favor of configuration by @c-dilks in #400
• fix(ci): generate latest documentation on HEAD, not main by @c-dilks in #409
• feat: automate release note generation by @c-dilks in #410

New Contributors

• @dependabot[bot] made their first contribution in #389

Full Changelog: v1.0.0...v1.1.0

v1.0.0

⚠️ Breaking Changes ⚠️

⚠️ Run function enhancements

To facilitate integration plans with clas12root, we have enhanced algorithms' Run functions in 2 ways:

1. all Run functions now return bool, providing an event-level filter

• users do not have to use the return value, so this shouldn't be a breaking change for anyone
• AlgorithmSequence::Run will abort the sequence if any algorithm's Run call returns false
• users can use the following pattern, for more efficient usage:

  // in event loop
  if(!algorithm1.Run(...)) continue;
  if(!algorithm2.Run(...)) continue;
  if(!algorithm3.Run(...)) continue;

2. new algorithm-specific "specialized" Run functions, which operate on (lvalue) references to hipo::bank objects

• the original Run(hipo::banklist&) functions simply call the specialized Run functions; the specialized
  Run functions are meant to provide more flexibility for the user, since they are for anyone that doesn't use hipo::banklist
• they provide compatibility with clas12reader's hipo::bank-derived objects, facilitating clas12root integration plans
• example, from rga::MomentumCorrection

    bool Run(
        hipo::bank& particleBank,
        hipo::bank const& sectorBank,
        hipo::bank const& configBank) const;

PR: feat!: Run function enhancements by @c-dilks in #364

⚠️ rename and group algorithms by CLAS12 Run Group

We have added a new namespace, specific for RG-A algorithms; so now we have the following algorithm namespaces:

iguana::clas12       run-group independent algorithms for CLAS12
iguana::clas12::rga  RG-A specific algorithms
iguana::physics      physics algorithms (independent of CLAS12)

We will create additional Run-Group specific namespaces as algorithms are developed.

Important

The following algorithms have been moved into the rga namespace; two have also been renamed:

iguana::clas12::FiducialFilter     -> iguana::clas12::rga::FiducialFilterPass1
iguana::clas12::RGAFiducialFilter  -> iguana::clas12::rga::FiducialFilterPass2
iguana::clas12::FTEnergyCorrection -> iguana::clas12::rga::FTEnergyCorrection
iguana::clas12::MomentumCorrection -> iguana::clas12::rga::MomentumCorrection

If a user tries to use the old algorithm name:

• compilation should still work, to avoid breaking the API completely; compilation will likely not work for Fortran users, however
• the old algorithm will fail at runtime, printing guidance to the user, namely the new algorithm's name

PR: refactor!: rename and group algorithms by CLAS12 Run Group by @c-dilks in #375

⭐ Primary Changes ⭐

New Algorithms and Updates

• Fiducial cuts
  • Rga common analysis functions :: FiducialFilter by @tbhayward in #367
  • feat: Pass 1 RG-A PCAL ficucial cuts by @c-dilks in #342
• Momentum Corrections
  • fix: do not apply momentum corrections for unknown sector by @c-dilks in #373
• Vertex cuts
  • Updated RGA electron z-vertex cuts by @tbhayward in #362
• Physics
  • feat!: SIDIS kinematics missing mass squared and Breit frame rapidity by @c-dilks in #308
  • feat: algorithm for computing depolarization factors by @c-dilks in #332
  • fix: find electron by requiring FD trigger first by @c-dilks in #353

Miscellaneous Primary Changes

• API
  • feat: bindings for vector action functions by @c-dilks in #330
    • this means vector action functions are now fully supported in all languages
• Documentation
  • doc: add more details to the user guide by @c-dilks in #325
  • feat: demonstrate in examples how to handle algorithm results by @c-dilks in #329
• CI
  • ci!: use container-forge container images by @c-dilks in #340

🚧 Technical Changes 🚧

• build: streamline ROOT dependency handling by @c-dilks in #368
• build: use static project version number by @c-dilks in #331
• ci: cleanup validator artifact name by @c-dilks in #376
• ci: increase retention time for validation artifacts by @c-dilks in #344
• ci: re-enable coverage tests by @c-dilks in #313
• ci: test for reproducible build by @c-dilks in #320
• ci: validation artifacts should unzip to a single directory by @c-dilks in #374
• doc(ci): use Ubuntu runner, not container image, for downloading test data by @c-dilks in #341
• doc: RCDB option note in setup by @c-dilks in #349
• doc: explain why SectorFinder operates on all particles, and not just filtered particles by @c-dilks in #343
• doc: note about bool configuration option issue by @c-dilks in #348
• feat: particle::get utility function by @c-dilks in #315
• feat: add energy to CalorimeterLinker output bank REC::Particle::Calorimeter by @c-dilks in #355
• fix(build): bump hipopy requirement, since CMake v4 has been released by @c-dilks in #339
• fix(build): check for libmariadb pkg-config by @c-dilks in #327
• fix(ci): don't apt upgrade by @c-dilks in #366
• fix(this_iguana.sh): prioritize Iguana in all path-type env vars by @c-dilks in #350
• fix: add missing algorithms to CODEOWNERS by @c-dilks in #372
• fix: centralize creator banks and set unique IDs by @c-dilks in #306
• fix: do not include GBT models in algorithm header by @c-dilks in #311
• fix: documentation for RGAFiducialFilter by @c-dilks in #371
• fix: don't assert real z-vertex cuts in hard-coded tests by @c-dilks in #363
• fix: force usage of off-site RCDB URI by @c-dilks in #357
• fix: remove cross check warnings for cross-checked algorithms by @c-dilks in #361
• fix: revert workaround -Wstringop-overflow warnings from fmt by @c-dilks in #319
• fix: suppress all hipo::structure UBSan alignment errors by @c-dilks in #314
• refactor!: remove unused DetectorTypes by @c-dilks in #365
• refactor(SectorFinder): use DetectorType enumerator by @c-dilks in #356
• style: auto-format settings and pre-commit hook by @c-dilks in #377
• style: improve 2D plot color palette by @c-dilks in #345

New Contributors

• @tbhayward made their first contribution in #362

Full Changelog: v0.8.0...v1.0.0

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