[{"_1":2,"_163":-5,"_164":-5},"loaderData",{"_3":4,"_18":19,"_26":27,"_142":143},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16,"_17":11},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","dockerRebrandTour","routes/_layout",{"_20":-5,"_21":22,"_23":22,"_24":11,"_25":22},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_28":29,"_30":-5,"_31":11,"_32":11,"_33":34,"_35":36,"_37":-5,"_38":11,"_39":40,"_89":-5,"_90":91,"_130":-5,"_131":11,"_132":22,"_133":11,"_134":11,"_135":-5,"_136":11,"_137":-5,"_138":139,"_140":92,"_141":-7},"canonicalUrl","https://hub.docker.com/r/wrathematics/fml/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","wrathematics","reponame","fml","cloudBuildSource","isAutobuildsAvailable","repo",{"_41":42,"_43":44,"_46":47,"_48":49,"_50":11,"_51":52,"_53":54,"_55":56,"_58":36,"_33":34,"_59":60,"_61":45,"_62":63,"_64":65,"_66":67,"_68":-5,"_69":63,"_70":71,"_72":11,"_73":34,"_74":75,"_80":11,"_81":82,"_86":34,"_87":88},"categories",[],"content_types",[45],"image","date_registered","2020-01-29T00:48:31.251018Z","description","Fused Matrix Library","is_private","last_updated","2020-01-29T01:04:13.450304Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[57],"application/vnd.docker.container.image.v1+json","name","pull_count",1115,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# fml\n\n* **Version:** 0.1-0\n* **Status:** [![Build Status](https://travis-ci.org/wrathematics/fml.png)](https://travis-ci.org/wrathematics/fml)\n* **License:** [BSL-1.0](http://opensource.org/licenses/BSL-1.0)\n* **Project home**: https://github.com/wrathematics/fml\n* **Bug reports**: https://github.com/wrathematics/fml/issues\n* **Documentation**: http://librestats.com/fml/html/index.html\n\n\n

\n\nfml is the Fused Matrix Library, a multi-source, header-only C++ library for dense matrix computing. The emphasis is on real-valued matrix types (`float`, `double`, and `__half`) for numerical operations useful for data analysis.\n\nThe goal of fml is to be \"medium-level\". That is, high-level compared to working directly with e.g. the BLAS or CUDA™, but low(er)-level compared to other C++ matrix frameworks. Some knowledge of the use of LAPACK will make many choices in fml make more sense.\n\nThe library provides 4 main classes: `cpumat`, `gpumat`, `parmat`, and `mpimat`. These are mostly what they sound like, but the particular details are:\n\n* CPU: Single node cpu computing (multi-threaded if using multi-threaded BLAS and linking with OpenMP).\n* GPU: Single gpu computing.\n* MPI: Multi-node computing via ScaLAPACK (+gpus if using [SLATE](http://icl.utk.edu/slate/)).\n* PAR: Multi-node and/or multi-gpu computing.\n\nThere are some differences in how objects of any particular type are constructed. But the high level APIs are largely the same between the objects. The goal is to be able to quickly create laptop-scale prototypes that are then easily converted into large scale gpu/multi-node/multi-gpu/multi-node+multi-gpu codes.\n\n\n\n## Installation\n\nThe library is header-only so no installation is strictly necessary. You can just include a copy/submodule in your project. However, if you want some analogue of `make install`, then you could do something like:\n\n```bash\nln -s ./src /usr/include/fml\n```\n\n\n\n## Dependencies and Other Software\n\nThere are no external header dependencies, but there are some shared libraries you need to have (more information below):\n\n* CPU code needs [LAPACK](http://performance.netlib.org/lapack/) (I recommend [OpenBLAS](https://github.com/xianyi/OpenBLAS))\n* GPU code needs [NVIDIA® CUDA™](https://developer.nvidia.com/cuda-downloads)\n* MPI code needs [ScaLAPACK](http://performance.netlib.org/scalapack/)\n* PAR code needs the libraries required by the CPU and/or GPU features, noted above.\n\nOther software we use:\n\n* Tests use [catch2](https://github.com/catchorg/Catch2) (a copy of which is included under `tests/`).\n\nYou can find some examples of how to use the library in the `examples/` tree. Right now there is no real build system beyond some ad hoc makefiles; but ad hoc is better than no hoc.\n\nDepending on which class(es) you want to use, here are some general guidelines for using the library in your own project:\n\n* CPU: `cpumat`\n - Compile with your favorite C++ compiler.\n - Link with LAPACK and BLAS (and ideally with OpenMP).\n* GPU: `gpumat`\n - Compile with `nvcc`.\n - For most functionality, link with libcudart, libcublas, and libcusolver. Link with libcurand if using the random generators. Link with libnvidia-ml if using nvml (if you're only using this, then you don't need `nvcc`; an ordinary C++ compiler will do). If you have CUDA installed and do not know what to link with, there is no harm in linking with all of these.\n* MPI: `mpimat`\n - Compile with `mpicxx`.\n - Link with libscalapack.\n* PAR: `parmat`\n - Compile with `mpicxx`.\n - Link with CPU stuff if using `parmat_cpu`; link with GPU stuff if using `parmat_gpu` (you can use both).\n\nCheck the makefiles in the `examples/` tree if none of that makes sense.\n\n\n\n## High-Level Language Bindings\n\n* R bindings: [fmlr](https://github.com/wrathematics/fmlr)\n\n\n\n## API Stability\n\nThe project is young and things are still mostly evolving. The current status is:\n\n* Frozen - Existing APIs will not be developed further.\n - none\n* Stable - Existing APIs are not expected to change. Some new features may be added slowly.\n - none\n* Stabilizing - Core class naming and construction/destruction is probably finalized. Function/method names and arguments are solidifying, but may change somewhat. New features are still being developed.\n - cpumat/gpumat/mpimat classes\n - cpuhelpers namespace functions\n - gpuhelpers namespace functions\n - linalg namespace (all but parmat)\n* Evolving - Function/method names and arguments are subject to change. New features are actively being developed.\n - mpihelpers namespace functions\n* Experimental - Nothing is remotely finalized.\n - parmat - all functions and methods\n\nInternals are evolving and subject to change at basically any time.\n\n\n\n## Example\n\nHere's a simple example computing the SVD with some data held on a single CPU:\n\n```C++\n#include \n#include \n\n\nint main()\n{\n len_t m = 3;\n len_t n = 2;\n \n cpumat x(m, n);\n x.fill_linspace(1.f, (float)m*n);\n \n x.info();\n x.print(0);\n \n cpuvec s;\n linalg::svd(x, s);\n \n s.info();\n s.print();\n \n return 0;\n}\n```\n\nSave as `svd.cpp` and build with:\n\n```bash\ng++ -I/path/to/fml/src -fopenmp svd.cpp -o svd -llapack -lblas\n```\n\nYou should see output like\n\n```\n# cpumat 3x2 type=f\n1 4 \n2 5 \n3 6 \n\n# cpuvec 2 type=f\n9.5080 0.7729 \n```\n\nThe API is largely the same if we change the object storage, but we have to change the object initialization. For example, if `x` is an object of class `mpimat`, we still call `linalg::svd(x, s)`. The differences lie in the creation of the objects. Here is how we might change the above example to use distributed data:\n\n```C++\n#include \n#include \n\n\nint main()\n{\n grid g = grid(PROC_GRID_SQUARE);\n g.info();\n \n len_t m = 3;\n len_t n = 2;\n \n mpimat x(g, m, n, 1, 1);\n x.fill_linspace(1.f, (float)m*n);\n \n x.info();\n x.print(0);\n \n cpuvec s;\n linalg::svd(x, s);\n \n if (g.rank0())\n {\n s.info();\n s.print();\n }\n \n g.exit();\n g.finalize();\n \n return 0;\n}\n```\n\nIn practice, using such small block sizes for an MPI matrix is probably not a good idea; we only do so for the sake of demonstration (we want each process to own some data). We can build this new example via:\n\n```bash\nmpicxx -I/path/to/fml/src svd.cpp -fopenmp svd.cpp -o svd -lscalapack-openmpi\n```\n\nWe can launch the example with multiple processes via\n\n```bash\nmpirun -np 4 ./svd\n```\n\nAnd here we see:\n\n```\n## Grid 0 2x2\n\n# mpimat 3x2 on 2x2 grid type=f\n1 4 \n2 5 \n3 6 \n\n# cpuvec 2 type=f\n9.5080 0.7729 \n```\n\n\n\n## Philosophy and Similar Projects\n\nSome similar C/C++ projects worth mentioning:\n\n* [Armadillo](http://arma.sourceforge.net/)\n* [Eigen](http://eigen.tuxfamily.org/)\n* [Boost](http://www.boost.org/)\n* [PETSc](https://www.mcs.anl.gov/petsc/)\n* [GSL](https://www.gnu.org/software/gsl/)\n\nThese are all great libraries which have stood the test of time. Armadillo in particular is worthy of a look, as it has a very nice interface and very extensive set of functions. However, to my knowledge, all of these focus exclusively on CPU computing. There are some extensions to Armadillo and Eigen for GPU computing. And for gemm-heavy codes, you can use [nvblas](https://docs.nvidia.com/cuda/nvblas/index.html) to offload some work to the GPU, but this doesn't always achieve good performance. And none of the above include distributed computing, except for PETSc which focuses on sparse matrices.\n\nThere are probably many other C++ frameworks in this arena, but none to my knowledge have a similar scope to fml.\n\nProbably the biggest influence on my thinking for this library is the [pbdR package ecosystem](https://github.com/RBigData) for HPC with the R language, which I have worked on for many years now. Some obvious parallels are:\n\n* [float](https://github.com/wrathematics/float) - CPU/GPU\n* [kazaam](https://github.com/RBigData/kazaam) - PAR\n* [pbdDMAT](https://github.com/RBigData/pbdDMAT) - MPI\n\nThe basic philosophy of fml is:\n\n* Be relatively small and self-contained.\n* Follow general C++ conventions by default (like RAII and exceptions), but give the ability to break these for the sake of performance.\n* Changing a code from one object type to another should be very simple, ideally with no changes to the source (the internals will simply **Do The Right Thing (tm)**), with the exception of:\n - object creation\n - printing (e.g. printing on only one MPI rank)\n* Use a permissive open source license.\n","has_starred","hub_user","immutable_tags_settings",{"_76":11,"_77":78},"enabled","rules",[79],".*","is_automated","permissions",{"_83":22,"_84":11,"_85":11},"read","write","admin","user","storage_size",1696883427,"orgData","recentTags",[92],{"_93":45,"_94":95,"_96":97,"_98":99,"_100":101,"_51":119,"_120":95,"_121":34,"_122":57,"_58":123,"_124":125,"_126":110,"_127":119,"_128":67,"_129":22},"content_type","creator",1809514,"full_size",1696870442,"id",84419786,"images",[102],{"_103":104,"_105":106,"_107":108,"_109":110,"_111":112,"_113":114,"_115":108,"_116":-5,"_117":97,"_64":67,"_118":-5},"architecture","amd64","digest","sha256:c996a86f3b79473945c9b2035172a20dd693718ac8884e17e06ec83a92ea50a3","features","","last_pulled","2026-10-20T13:25:43.902744256Z","last_pushed","2020-01-29T01:04:13Z","os","linux","os_features","os_version","size","variant","2020-01-29T01:04:12.999153Z","last_updater","last_updater_username","media_type","latest","repository",8391234,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxRunInCloud","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_39":144,"_151":152,"_138":161,"_162":11},{"_41":145,"_43":146,"_46":47,"_48":49,"_50":11,"_51":52,"_53":54,"_55":147,"_58":36,"_33":34,"_59":60,"_61":45,"_62":63,"_64":65,"_66":67,"_68":-5,"_69":63,"_70":71,"_72":11,"_73":34,"_74":148,"_80":11,"_81":150,"_86":34,"_87":88},[],[45],[57],{"_76":11,"_77":149},[79],{"_83":22,"_84":11,"_85":11},"tags",{"_153":65,"_154":-5,"_155":-5,"_156":157},"count","next","previous","results",[158],{"_93":45,"_94":95,"_96":97,"_98":99,"_100":159,"_51":119,"_120":95,"_121":34,"_122":57,"_58":123,"_124":125,"_126":110,"_127":119,"_128":67,"_129":22},[160],{"_103":104,"_105":106,"_107":108,"_109":110,"_111":112,"_113":114,"_115":108,"_116":-5,"_117":97,"_64":67,"_118":-5},[],"canDeleteTags","actionData","errors"]

wrathematics/fml

Tags for wrathematics/fml