Release Notes

flecsi:: qualification is omitted throughout.

Changes in v2.3.0 (June 20 2024)

Possible incompatibilities

  • Topologies

    • narray auxiliaries between two colors are owned by the upper color.

Deprecated

  • Build

    • ENABLE_DOXYGEN_WARN — ignored since 2.2.0

    • FLOG_ENABLE_COLOR_OUTPUT, FLOG_SERIALIZATION_INTERVAL, and FLOG_STRIP_LEVEL — use flog::config

  • Runtime

    • initialize, start, finalize, run::status, and control::check_status — use runtime and, optionally, getopt

    • program — use argv directly

    • Use of a control policy’s node_policy type — remove it

    • control::execute — use control::invoke or runtime::control with run::control_base and not node_policy

    • option_value and needing one in a program_option validation function — accept the option type instead

    • flecsi/run/control.hh — use flecsi/runtime.hh

  • Data

    • coloring_slot — use specialization::mpi_coloring

  • Execution

    • Constructing a trace with an id — use the default constructor

  • Topologies

    • specialization::cslot — use mpi_coloring

    • flecsi/topo/narray/interface.hh — use flecsi/topology.hh

    • narray_impl::index_definition::create_plan — always ignored

    • narray_base::domain and is_low, is_high, is_interior, is_degenerate, global_id, size, range, and offset in narray::access — use axis

  • Utilities

    • util::dag, util::reorder, util::reorder_destructive, util::intersects, util::set_intersection, util::set_union, util::set_difference — superfluous

    • Passing binary functors to mpi::one_to_allv, mpi::one_to_alli, and mpi::all_to_allv — remove second parameter or use ranges

    • flecsi/util/annotation.hh, flecsi/util/array_ref.hh, flecsi/util/color_map.hh, flecsi/util/common.hh, flecsi/util/dag.hh, flecsi/util/demangle.hh, flecsi/util/dimensioned_array.hh, flecsi/util/mpi.hh, flecsi/util/reorder.hh, flecsi/util/serialize.hh, flecsi/util/set_intersection.hh, flecsi/util/set_utils.hh, flecsi/util/unit.hh — use flecsi/utilities.hh

New features

  • Build

    • flecsi/config.hh provides information about the build of FleCSI in use.

    • A CMake utility library is provided. (This was added without a release note in 2.2.0.)

    • flecsi_add_target_test is a CMake function to define tests using existing targets.

    • flecsi_add_test can use a launcher command to wrap the test execution.

  • Runtime

    • runtime.hh provides access specifically to the runtime model.

    • runtime represents FleCSI initialization as an object.

    • getopt parses user-defined command-line options.

    • run::dependencies_guard allows for application control over initialization of FleCSI dependencies.

    • control::invoke executes a control model with a policy object constructed from arguments provided.

    • run::call is a trivial predefined control model.

    • program_option validation functions can accept the option value directly.

    • task_names returns a mapping of shortened registered FleCSI task names to their full signature.

    • initialize accepts const char * const * for better compatibility.

  • Data

    • topology_slot is now movable; empty slots may be detected with topology_slot::is_allocated.

  • Execution

    • test convenience function launches unit test tasks.

    • trace objects can be move-assigned.

  • Topologies

    • specialization::mpi_coloring creates a coloring eagerly.

    • topo::make_ids<S>(r) is a convenience function to convert a range r of ordinary integers into a range of id<S> objects.

    • unstructured_base::bounding_box computes the axis-aligned bounding box of a mesh.

    • unstructured::special_field is the field definition for special-entity lists.

    • unstructured::get_special_entities allows access to individual special-entity lists.

    • narray_base::distribute and narray_base::make_axes help construct coloring objects.

    • The names axis_definition and index_definition are available in narray_base.

    • axis, axis_color, axis_layout, and axis_info in narray_base describe axes in topology accessors.

    • ntree is a topology that tracks interacting particles. It only supports Legion as a backend and does not support ragged or sparse fields.

  • Legion backend

    • Task names are now shortened for better usability in Legion profiling tools. See Profiling with Legion for details.

  • Utilities

    • transform applies a transformation functor to a range.

    • partition_point and binary_index find values in sorted ranges.

    • permutation_view accesses a subset of a range.

    • mpi::one_to_allv, mpi::one_to_alli, and mpi::all_to_allv additionally accept ranges and unary functors.

    • KDTree efficiently finds intersections between shapes.

    • Values may be included in expectation/assertion failure messages.

    • FLECSI_DEVICE_CODE is a macro defined during the device compilation for either CUDA or HIP.

  • Logging

    • flog::config is the collection of FLOG options that can be changed at runtime.

    • flog::tags returns the names of all defined tags.

Fixed

  • Build

    • flecsi_add_sphinx_target doesn’t use -n (which can break for references into other libraries).

  • Data

    • The size of one color of an index space can exceed \(2^{32}\) (if FLECSI_ID_TYPE is configured approprately).

  • Execution

    • Tasks may be declared noexcept. (This was fixed but not documented in 2.2.1.)

  • Topologies

    • narray

      • index_definition::diagonals being false works. (This was fixed but not documented in 2.2.1.)

      • Periodic axes require equal boundary and halo depths (differing values never worked reliably).

      • Auxiliary axes support full_ghosts and periodic properly.

    • unstructured supports num_intervals of 0.

  • Legion backend

    • omp tasks now work in builds with GPU support.

    • MPI tasks properly wait on previously launched tasks.

    • Memory usage for implementing ghost copies has been significantly reduced.

    • Processes with multiple CPUs schedule tasks more efficiently.

    • Launches of zero point tasks succeed (vacuously).

    • The --Xbackend -dm:memoize option is no longer required to enable tracing.

  • On-node parallelism

    • Custom reductions and reduced types work with Kokkos.

  • Utilities

    • one_to_alli no longer triggers a race condition.

  • Logging

    • Special options like --control-model and --help work reliably. (This was documented but not actually implemented in 2.2.1.)

    • FLOG messages are now variable size and are no longer truncated.

Changes in v2.2.1 (July 12 2023)

Fixed

  • Runtime

    • Control policy objects are value-initialized by run::control::execute.

    • Unrecognized options are properly rejected along with unrecognized positional arguments.

    • The same exit status is used for all erroneous command lines.

    • Control-model graphs are labeled with the program name.

    • Control model output strips parameters, return values, wrappers, and common namespaces from actions for better readability.

  • Data

    • ragged accessors with wo privileges work for GPU tasks. (The field type must still be trivially default-constructible.)

  • Utilities

    • transform_view supports pointers to members (though not during constant evaluation).

Changes in v2.2.0 (April 14 2023)

Possible incompatibilities

  • Build

    • FLECSI_RUNTIME_MODEL is renamed to FLECSI_BACKEND (it never referred to Runtime Model).

  • Utilities

    • util::mdspan::operator() is removed (it had an inconsistent argument order).

Deprecated

  • Runtime

    • control::state — derive the control policy type from control_base and define actions accepting a reference to it

    • run::control_point — use control_base::point

    • run::cycle — use control_base::cycle

  • Data

    • global_topology and process_topology — create instances of topo::global and topo::index as needed

  • Utilities

    • in util::annotation, begin and end — use guard or rguard

  • Logging

    • The namespace flecsi::log — use flecsi::flog instead

    • The CMAKE option FLOG_SERIALIZATION_THRESHOLD is not used anymore

New features

  • Build

    • The HIP compiler is supported.

  • Runtime

    • Control policies may inherit from control_base to be provided to actions, to allow those actions to throw control_base::exception, and to limit their lifetime to that of control::execute.

    • control_base::meta defines special control points for a specialization’s use via control::meta.

    • New option --Xbackend to pass single backend arguments. Can be used multiple times.

  • Data

    • field_reference::get_elements and associated types allow control of the storage for elements of ragged/sparse fields.

    • launch::mapping allows field data to be accessed from other colors (using multi task parameters) with the Legion backend.

    • topology_slot::colors reports on the number of colors for an allocated topology.

    • reduction_accessor allows dense fields on a global topology to be updated collectively.

    • The particle layout supports efficient creation and destruction of unordered field elements.

    • Field definitions are copyable and may be destroyed after use.

    • Fields may be of non-portable types so long as they are used only by MPI tasks.

    • single accessors support -> to access the members of a field value of class type.

  • Execution

    • Tasks may be executed as omp, allowing efficient use of OpenMP.

    • exec::trace improves performance of loops when used with the Legion backend.

    • task_local objects define global variables with task-local values.

  • Topologies

    • unstructured represents unstructured meshes.

    • narray represents hyperrectangular arrays, including structured meshes.

    • global topology instances may be created with sizes other than 1. (All elements are shared together among all point tasks in an index launch.)

    • util::id and util::gid store topology-entity IDs.

  • MPI backend

    • The toc processor type is supported.

  • On-node parallelism

    • exec::parallel_for, forall, exec::parallel_reduce, and reduceall may be used without Kokkos enabled, in which case they run serially.

    • exec::mdiota_view provides support for multi dimensional ranges, with exec::full_range, exec::prefix_range and exec::sub_range options.

  • Utilities

    • unit.hh provides macros, based on Google Test, for writing unit tests in or outside of tasks.

    • serial provides a general-purpose serialization interface. It may be extended to allow additional types to be used as task parameters or with MPI communication.

    • mdcolex accesses a multi-dimensional array using Fortran-like syntax.

    • mpi::one_to_alli scatters generated and/or serialized data with bounded memory usage.

    • MPI communication functions compute values to send in rank order and support mutable functors.

    • substring_view represents part of another range.

    • equal_map and offsets represent partitions of integer ranges.

  • Logging

    • flog_fatal suppresses backtraces (already unavailable if NDEBUG is defined) unless FLECSI_BACKTRACE is set in the environment.

    • flog is a new name that avoids collisions with ::log in code lacking proper namespace qualifications.

Fixed

  • Build

    • HDF5 is supported by the CMake configuration.

    • Caliper is supported by the MPI backend.

    • Building with the MPI backend properly links to the threading library.

    • Added FLECSI_VERSION define to record version

  • Runtime

    • Certain control-flow graphs compile with Graphviz support and are drawn correctly.

    • --backend-args can be specified multiple times. The collected arguments are passed to the backend.

    • MPI and Kokkos are initialized with no arguments (so that they cannot misinterpret arguments not meant for them).

  • Data

    • Mutators support write-only privileges (which, as with accessors, are necessary to properly initialize fields).

    • Mutators work on fields over zero index points.

  • Topologies

    • Topology accessors that provide metadata for direct access in a toc task work properly when writable (although without such direct access in that case).

  • Legion backend

    • Certain user-level fields are allocated properly.

    • MPI tasks with reference parameters support argument conversions correctly.

    • Errors at process termination in certain configurations are avoided.

    • Accessors with both wo and na privileges are processed correctly.

  • MPI backend

    • exec::fold::min and exec::fold::max work with bool (but may be slower than using another type like int).

    • Index futures work properly when declared const.

    • Index futures work with bool return type.

  • On-node parallelism

    • More accessor and topology accessor functions are available on a device.

    • Several uses of “iterator” in documentation have been corrected to use “range”.

  • Logging

    • Tags work correctly in tasks executed in parallel.

    • Messages are sorted by timestamp correctly.

    • Exiting the process before flecsi::finalize does not crash.

Changes in v2.1.0 (April 16 2021)

New features

  • Topologies

    • topo::help is a convenient base class for specialization class templates that defines the non-dependent names in specialization.

Changes in v2.0.0 (March 30 2021)

The changes between versions 1 and 2 are extensive and so are merely summarized here. The broadest change is that macros are used only for on-node parallelism constructs and for logging. Some macro arguments become template arguments.

Removed

  • Data

    • flecsi_get_client_handle — use the topology slot directly

    • flecsi_get_handles, flecsi_get_handles_all, flecsi_is_at, flecsi_has_attribute_at, flecsi_has_attribute — will be provided differently by io

  • Execution

    • flecsi_register_task, flecsi_register_task_simple, flecsi_register_mpi_task, flecsi_register_mpi_task_simple — unneeded

    • specialization_tlt_init, specialization_spmd_init, execution::driver — the application provides main

    • flecsi_execute_task_simple — namespaces require no special treatment

    • flecsi_register_program — unneeded

    • flecsi_register_global_object, flecsi_set_global_object, flecsi_initialize_global_object, flecsi_get_global_object — use non-local variables directly, with the same restrictions

    • flecsi_register_reduction_operation — unneeded

  • Topologies

    • Topology element id() — iteration produces indices

    • Unstructured mesh — will be reimplemented

Other incompatibilities

  • Data

    • flecsi_register_data_client — now topology slots

    • flecsi_register_field, flecsi_register_global, flecsi_register_color — now field::definition, or a container of same to implement multiple versions

    • flecsi_get_handle, flecsi_get_global, flecsi_get_color, flecsi_get_mutator — now definition::operator()

    • data_client_handle_u<T,P> — now T::accessor<P>

    • dense_accessor, ragged_accessor, ragged_mutator, sparse_accessor, sparse_mutator — now definition::accessor or definition::mutator

      • ragged fields have a std::vector-like interface at each index point

      • sparse fields have a std::map-like interface at each index point

  • Execution

    • flecsi_execute_task — now execute

    • flecsi_execute_mpi_task, flecsi_execute_mpi_task_simple — pass mpi to execute

    • flecsi_execute_reduction_task — now reduce

    • flecsi_color(), flecsi_colors() — now color() and colors()

    • flecsi_register_function, flecsi_execute_function, flecsi_function_handle, flecsi_define_function_type — now exec::make_partial

    • execution::flecsi_future — now future, with a simpler interface

  • Topologies

    • Specializations inherit from topo::specialization rather than from a core topology type directly.

New features

  • Runtime

    • Application command-line options can be specified using the program_option class template and associated helper functions.

    • The control class template is used to define an extensible control model for an application.

  • Data

    • The raw and single layouts support special cases of field usage.

  • Execution

    • Tasks can be (specializations of) function templates.

    • Tasks can accept parameters of dynamic size (e.g., std::vector<double>), although passing large objects is inefficient.

    • Index launches can be of any number of point tasks (determined by the task’s arguments, including exec::launch_domain).

    • test conveniently executes tasks for unit testing.

  • Topologies

    • Multiple user-defined topology instances may exist sequentially or simultaneously.