Repository files navigation

CPFloat is a C library for simulating low-precision floating-point arithmetics. CPFloat provides efficient routines for rounding, performing arithmetic operations, evaluating mathematical functions, and querying properties of the simulated low-precision format. Internally, numbers are stored infloat ordouble arrays. The low-precision format (target format) follows an extension of the formats defined in the IEEE 754 standard[5] and is entirely specified by four parameters:

• a positive integerp, which represents the number of digits of precision;
• a positive integere_min, which represents the minimum supported exponent;
• a positive integere_max, which represents the maximum supported exponent; and
• a Boolean variable σ, set totrue if subnormal are supported and tofalse otherwise.

Valid choices ofp,e_min, ande_max depend on the format in which the converted numbers are to be stored (storage format). A more extensive description of the characteristics of the low-precision formats that can be used, together with more details on admissible values forp,e_min,e_max, andσ can be found in[1].

The library was originally intended as a faster version of the MATLAB functionchop[2], which isavailable on GitHub.The latest versions of the library have a variety of subtle differences compared withchop.

• Since14 June 2022,chop supports specifying the function for generating random numbers. The MEX interface of CPFloat does not offer this capability, as the pseudo-random numbers used are generated in C and not in MATLAB.
• Since v0.6.0, CPFloat allows users to specifye_min ande_max separately. In earlier versions, users can only specifye_max, whilee_min is set to 1 –e_max.
• Since v0.6.0, the default 8-bit formatE4M3 hase_max = 8 ande_min = –6, which is consistent with the homonymous format in the December 2023 revision of the OCP 8-bit Floating Point Specification (OFP8)[3]. Inchop,e_max = 7 ande_min = –6.

The code to reproduce the results of the tests in[1] isavailable on GitHub.

The only (optional) dependency of CPFloat is theC implementation of thePCG Library, which provides a variety of high-quality pseudo-random number generators. For an in-depth discussion of the algorithms underlying the PCG Library, we recommend thepaper byMelissa O'Neill[4]. If the header filepcg_variants.h ininclude/pcg-c/include/pcg_variants.h is not included at compile-time with the--include option, then CPFloat relies on the default C pseudo-random number generator.

The PCG Library is free software (see theLicensing information below), and its generators are more efficient, reliable, and flexible than any combination of the functionssrand,rand, andrand_r from the C standard library. A warning is issued at compile time if the location ofpcg_variant.h is not specified correctly.

Compiling the MEX interface requires a reasonably recent version of MATLAB or Octave.

Testing the MEX interface requires the functionfloat_params, which isavailable on GitHub. The unit tests for the C implementation intest/cpfloat_test.ts require thecheck unit testing framework for C, including thecheckmk script, and thesubunit protocol.

No installation is needed in order to use CPFloat as a header-only library. The shared and static libraries can be built with

make lib

If the compilation is successful, the header and library files of CPFloat will be located in thebuild/include andbuild/lib directories, respectively.The library can be installed in<path> with

make install --prefix=<path>

which copies the header and library files in<path>/include and<path>/lib, respectively.The default value of<path>, which is used if the--prefix option is not supplied, is/usr/local.

The MEX interface can be compiled automatically with either

make mexmat # Compile MEX interface for MATLAB.

or

make mexoct # Compile MEX interface for Octave.

These two commands compile and autotune the MEX interface in MATLAB and Octave, respectively, by using the functionsmex/cpfloat_compile.m andmex/cpfloat_autotune.m. To use the interface, thebin/ folder must be in MATLAB's search path.

On a system where themake build automation tool is not available, we recommend building the MEX interface by running the scriptcpfloat_compile_nomake.m in themex/ folder. The script attempts to compile and autotune the MEX interface using the default C compiler. The following code will download the repository as a ZIP file, inflate it, and try to compile it:

zip_url='https://codeload.github.com/north-numerical-computing/cpfloat/zip/refs/heads/main';unzip(zip_url);movefile('cpfloat-main','cpfloat')cd('cpfloat/mex');cpfloat_compile_nomake

A different compiler can be used by setting the value of the variablecompilerpath appropriately.If the chosen compiler does not support OpenMP, only the sequential version of the algorithm will be produced and no autotuning will take place.

On Windows, we have not been able to compile the PCG Library using the C compiler recommended by MATLAB. Therefore, the script uses the pseudo-random number generator in the C standard library by default.

CPFloat provides a sequential and a parallel implementation of the rounding functions. OpenMP introduces some overhead, and using a single thread is typically faster for arrays with few elements. Therefore, the library provides a facility to switch between the single-threaded and the multi-threaded variants automatically, depending on the size of the input. The threshold is machine-dependent, and the best value for a given system can be found by invoking

make autotune

which compiles the filesrc/cpfloat_autotune.c, runs it, and updates the filessrc/cpfloat_threshold_binary32.h andsrc/cpfloat_threshold_binary64.h. This procedure is run automatically when building the shared and static libraries.

The documentation of CPFloat can be generated with the command

make docs

which relies onDoxygen to format the Javadoc-style comments in the source files, and onSphinx, with theBreathe andExhale extensions, to generate the HTML version of the documentation that can be found in thedocs/html/ directory.

CPFloat can be used as a header-only, shared, or static library. Examples for these three scenarios can be found in theMakefile (cf. targets$(BINDIR)cpfloat_test,$(BINDIR)libcpfloat_shared_test, and$(BINDIR)libcpfloat_static_test, respectively). Here we provide a brief summary.

• Header-only library. The only requirement is that the files in thesrc/ directory be in the include path of the compiler. In order to use the PCG Library, one can either:

  • specify the path of the filepcg_variants.h using the preprocessor option--include (see the variableCFLAGS in theMakefile for an example); or
  • make sure thatpcg_variants.h is in the include path and uncomment the preprocessor instruction on line 34 ofsrc/cpfloat_definitions.h, that is,/* #include "pcg_variants.h" */. In either case, it is necessary link the executable against thepcg-random library, which can be obtained by passing the option-lpcg-random to the linker. The librarylibpcg-random.a must be in the load path.

• Shared library. The five header files in thebuild/include directory must be in the include path of the compiler. The options-lcpfloat and-lm must be passed to the linker, and the librarieslibcpfloat.so andm.so must be in the load path.

• Static library. The static library uses the same five header files as the shared library, which are located in thebuild/include and must be in the include path of the compiler. Executable must be linked with the-static and-lcpfloat options, and the library filelibcpfloat.a must be in the load path. Linking against the math library is not needed in this case.

Thetest/ directory contains two sets of test, one for the C library and one for the MEX interface. The unit tests for the C implementation require thecheck library, and can be run with

make ctest

for the header-only library or with

make libtest

for the shared and static libraries. The two commands use the same batch of unit tests, which is generated from the filetest/cpfloat_test.ts using thecheckmk script.The Makefile targetcoverage measures the code coverage using GNUgcov on the same set of tests.

The MEX interface can be tested by using either

make mtest # Test MEX interface using MATLAB.

or

make otest # Test MEX interface using Octave.

These two commands run, in MATLAB and Octave respectively, the functiontest/cpfloat_test.m. This set of tests is based on the MATLAB scripttest_chop.m,available on GitHub: some changes were necessary in order to make it compatible with Octave.

[1] Massimiliano Fasi and Mantas Mikaitis.CPFloat: A C library for simulating low-precision arithmetic. ACM Trans. Math. Softw., 49(2), Article No.: 18, June 2023.

[2] Nicholas J. Higham and Srikara Pranesh,Simulating Low Precision Floating-Point Arithmetic, SIAM J. Sci. Comput., 41, C585-C602, 2019.

[3] Paulius Micikevicius, Stuart Oberman, Pradeep Dubey, Marius Cornea, Andres Rodriguez, Ian Bratt, Richard Grisenthwaite, Norm Jouppi, Chiachen Chou, Amber Huffman, Michael Schulte, Ralph Wittig, Dharmesh Jani, Summer Deng.OCP 8-bit Floating Point Specification (OFP8), pp. 1–16, Revision 1.0, Open Compute Project, June 2023. Revised December 2023.

[4] Melissa E. O'Neill,PCG: A family of simple fast space-efficient statistically good algorithms for random number generation, Technical report HMC-CS-2014-0905, Harvey Mudd College, Claremont, CA, September 2014.

[5]754-2019 IEEE Standard for Floating-Point Arithmetic, pp. 1–84, Institute of Electrical and Electronics Engineers, July 2019. Revision of IEEE Std 754-2008.

The library was written by Massimiliano Fasi and Mantas Mikaitis. We thank Nicolas Louvet, Theo Mary, Ian McInerney, and Siegfried Rump for reporting bugs and suggesting improvements.

CPFloat is distributed under the GNU Lesser General Public License, Version 2.1or later (seeLICENSE.md). Please contact us if you would like to use CPFloat in an open source project distributed under the terms of a license that is incompatible with the GNU LGPL. We might be able to relicense the software for you.

The PCG Library is distributed under the terms of either theApache License, Version 2.0 or theExpat License, at the option of the user.

The MATLAB functionfloat_params is distributed under the terms of theBSD 2-Clause "Simplified" License.

The MATLAB functionchop is distributed under the terms of theBSD 2-Clause "Simplified" License.