Mitica - Flexible Hadron Polarization Analysis Code

Description

Mitica is a specialized code designed to implement and compare various hadron polarization formulas, including a novel approach based on quantum kinetic theory. This code builds upon and extensively adapts algorithms from existing particlization frameworks, maintaining the use of OpenMP for optimized performance and faster execution.

Mitica enables direct comparisons between the quantum kinetic theory-based formula and existing models, particularly those based on the local thermal equilibrium approximation. The quantum kinetic theory component of Mitica is based on the work presented in Phys. Rev. D 106 (2022) 9, L091901 by Nora Weickgenannt, David Wagner, Enrico Speranza, and Dirk H. Rischke. This comparative analysis will assess the alignment of the quantum kinetic theory with experimental data relative to established models, with findings to be detailed in an upcoming publication.

Key Features

Flexible Framework: Supports easy switching between different hadron polarization formulas, enabling comprehensive comparative studies.
Optimized Performance: Continues to use OpenMP to enhance performance, ensuring efficient execution while adapting existing algorithms.
Modular Design: The code is structured to facilitate seamless integration with different hydrodynamic simulations, enhancing versatility and applicability in various research contexts.
Modern Development Tools: Implements modern software development practices, including unit testing with Google Test and performance benchmarking, to ensure reliability and efficiency.

Installation

CMake

The project can be compiled using CMake. Use the provided bash scripts for Mac and Linux:

Mac: build_darwin.bash
Linux: build_linux.bash

These scripts build the main project as well as benchmarks and tests.

Boost

It is easy to install

Mac brew install boost
Ubuntu sudo apt-get install libboost-all-dev

Google Benchmark

Benchmark files are located in the ./test directory. To install Google Benchmark, follow the installation instructions.

Adding a Benchmark

To add a benchmark, create a method in one of the bench_*.cpp files:

static void bm_foo(benchmark::State &state)
{
    for (auto _ : state)
    {
        // do something
    }
}

BENCHMARK(bm_foo);

Then update CMakeLists.txt:


add_executable(
    bench_your_name
    test/bench_your_name.cpp
    src/...
)
target_link_libraries(bench_your_name PUBLIC benchmark::benchmark)
#if you need OpenMP
if(OpenMP_CXX_FOUND)
    # If OpenMP is found, add the OpenMP flags to the compiler options
    target_compile_options(bench_your_name PUBLIC ${OpenMP_CXX_FLAGS})
    # Link the OpenMP library to the test executable
    target_link_libraries(bench_your_name PUBLIC OpenMP::OpenMP_CXX)
endif()

Google Test

Test files are located in the ./test directory. Install Google Test following the quickstart guide.

Adding a test

Create a test file in the ./test folder:

namespace
{
    class FooTest : public my_test
    {
    protected:
    void SetUp() override
        {
        }


add_executable(
    test_utils
    test/test_utils.cpp 
    src/utils.cpp   
)
target_link_libraries(
    test_utils
    GTest::gtest_main
)
include(GoogleTest)
gtest_discover_tests(test_utils)

Namespaces

`namespace utils`

Enums: Program options (program_modes, accept_modes, polarization_modes, program_options).
Random Generators: Simple random generators in C++ style.
Constants: Constants from the old const.h.
Error Templates: absolute_error and relative_error templates.
Command Reader: read_cmd for reading command arguments.
Progress Bar: show_progress for long operations.
Linspace: Generates a range for various parameters.
Four-vector and Tensor: Simple four-vector (std::array) and rank-2 Minkowski tensor.

`namespace utils::geometry`

Encapsulates a Minkowski four-vector four_vector that maintains its index structure and enables vector operations.
A rank-2 tensor wrapper: not implemented.

`namespace hydro`

hydro::I_cell< V, T >: interface for a hypersurface cell with V being the four vetor type and T being the rank-2 tensor type.
hydro::I_solution< C, V, T >: interface for an analytical solution for testing purpsoes. C is the cell type that must be inherited from I_cell, V is the four vector's type, and T is the rank-2 tensor's type. Two implementations can be found in ./test folder: the ideal Bjorken flow ibjorken and the rigidly rotating cylinder rigid_cylinder:
```
class ibjorken : public hydro::I_solution<vhlle::fcell, ug::four_vector, utils::r2_tensor>
{
...
}
class rigid_cylinder : public hydro::I_solution<vhlle::fcell, ug::four_vector, utils::r2_tensor>
{
...
}
```
hydro::hypersurface< C >: a wrapper for the surface. In particular, it reads the surface data from a file using read (const std::string &i_file, utils::accept_modes mode). It uses paralleization if the code is compiled with OpenMP.
hydro::surface_stat< C >: struct that stores statistical data of the surface.

hydro::solution_factory< C, V, T >: singleton factory that is used for registeration and creation of analytical solutions. An example of the usage in ./test/test_bjorken.cpp is:

namespace ug = utils::geometry;
...
std::shared_ptr<hydro::solution_factory<vhlle::fcell, ug::four_vector, utils::r2_tensor>> factory =
        hydro::solution_factory<vhlle::fcell, ug::four_vector, utils::r2_tensor>::factory();
factory->regsiter_solution(ibjorken::get_name(),
                                   [...]()
                                   {
                                       return std::make_unique<ibjorken>(
                                           ibjorken(...));
                                   });
...
auto bjorken = factory->create(ibjorken::get_name());
bjorken->populate();
...

vhlle::fcell: a concrete implementation of I_cell.
Legacy: element, fsurface, hypersurface, hypersurface_wrapper, surface_info, t_surface_info: kept only for testing

`namespace powerhouse`

powerhouse::I_calculator: Interface for calculation. Implemented in powerhouse::examiner, and test/mock_calculator.
Polarization caclulators are not implemented yet.
Yield calculators are not implemented yet.

powerhouse::I_engine: A singlton factory that takes care of the calculations:

...
auto engine = powerhouse::I_engine<vhlle::fcell>::get(settings);
engine->init(hypersurface);
...
engine->run();
...
engine->write();

powerhouse::calculator_factory< C >: singleton factory that is used for registeration and creation of calculators. Calculators are registered, in main.cpp, as:

powerhouse::calculator_factory<vhlle::fcell>::factory()
    ->register_calculator(settings,
                          []()
                          {
                              return std::make_unique<powerhouse::examiner>();
                          });

It is also used in I_engine:

if (!_calculator)
{
std::lock_guard lock(_mutex);
_calculator = calculator_factory<C>::factory()->create_calculator(_settings);
}

I_particle: Interface for a particle which is implemtned in pdg_particle (a slight modification of Andrea Palermo's code). In I_engine::init:

if (!_particle_house)
{
std::lock_guard lock(_mutex);
_particle_house.reset(t_particle_house); // _particle_house is a pointer to I_particle
}

I_output Generic calculation output. Impelemented in exam_output. polarization_output and yield_output are placeholders for further deveoplemtns.

Program modes

Help:

./build/calc --help

Examine:

./build/calc -i input/input_file_name -o output/output_file_name -e [accept mode]

Yield:

./build/calc -i input/input_file_name -o output/output_file_name -y [accept mode] [-pn particle name | -pdg particle id]

Polarization: (not implemented yet)

./build/calc -i input/input_file_name -o output/output_file_name -p [accept mode] [polarization mode] [-pn particle name | -pdg particle id]

drlotus / mitica

readme