{"id":13819040,"url":"https://github.com/ShadenSmith/splatt","last_synced_at":"2025-05-16T04:32:35.158Z","repository":{"id":43394955,"uuid":"61401280","full_name":"ShadenSmith/splatt","owner":"ShadenSmith","description":"The Surprisingly ParalleL spArse Tensor Toolkit.","archived":false,"fork":false,"pushed_at":"2022-03-03T20:18:51.000Z","size":15740,"stargazers_count":69,"open_issues_count":5,"forks_count":29,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-12T21:12:17.565Z","etag":null,"topics":["cpd","machine-learning","mpi","openmp","parallel","tensor"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ShadenSmith.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-17T20:44:20.000Z","updated_at":"2024-10-01T05:51:42.000Z","dependencies_parsed_at":"2022-08-30T02:12:44.181Z","dependency_job_id":null,"html_url":"https://github.com/ShadenSmith/splatt","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShadenSmith%2Fsplatt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShadenSmith%2Fsplatt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShadenSmith%2Fsplatt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShadenSmith%2Fsplatt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ShadenSmith","download_url":"https://codeload.github.com/ShadenSmith/splatt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225405526,"owners_count":17469360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpd","machine-learning","mpi","openmp","parallel","tensor"],"created_at":"2024-08-04T08:00:38.412Z","updated_at":"2024-11-19T18:31:07.383Z","avatar_url":"https://github.com/ShadenSmith.png","language":"C","readme":"The Surprisingly ParalleL spArse Tensor Toolkit\n===============================================\n\n[![Build Status](https://travis-ci.org/ShadenSmith/splatt.svg?branch=master)](https://travis-ci.org/ShadenSmith/splatt)\n\nSPLATT is a library and C API for sparse tensor factorization. SPLATT supports\nshared-memory parallelism with OpenMP and distributed-memory parallelism with\nMPI.\n\n\nTensor Format\n-------------\nSPLATT expects tensors to be stored in 0- or 1-indexed coordinate format with\nnonzeros separated by newlines. Each line of of the file has the coordinates of\nthe nonzero  followed by the value, all separated by spaces.  The following is\nan example 2x2x3 tensor with 5 nonzeros:\n\n    # This is a comment\n    1 1 2 1.5\n    1 2 2 2.5\n    2 1 1 3.7\n    1 2 3 0.5\n    2 1 2 4.1\n\n\nBuilding \u0026 Installing\n---------------------\nSPLATT requires CMake and working BLAS/LAPACK libraries to run. In short,\n\n    $ ./configure \u0026\u0026 make\n\nwill build the SPLATT library and its executable. The executable will be found\nin `build/\u003carch\u003e/bin/`. You can also run\n\n    $ ./configure --help\n\nto see additional build options. To install,\n\n    $ make install\n\nwill suffice. The installation prefix can be chosen by adding a\n'--prefix=DIR' flag to configure.\n\n\nExecutable\n----------\nAfter building, an executable will found in the `build/` directory (or the\ninstallation prefix if SPLATT was installed). SPLATT builds a single executable\nwhich features a number of sub-commands:\n\n* cpd\n* check\n* convert\n* reorder\n* stats\n\nAll SPLATT commands are executed in the form\n\n    $ splatt CMD [OPTIONS]\n\nYou can execute\n\n    $ splatt CMD --help\n\nfor usage information of each command.\n\n### Example 1\n\n    $ splatt check mytensor.tns  --fix=fixed.tns\n\nThis runs `splatt-check` on 'mytensor.tns' and writes the fixed tensor to\n'fixed.tns'. The `splatt-check` routine finds empty slices and duplicate\nnonzero entries. Empty slices are indices in any mode which do not have any\nnonzero entries associated with them. Some SPLATT routines (including CPD)\nexpect there to be no empty slices, so running `splatt-check` on a new tensor\nis recommended.\n\n### Example 2\n\n    $ splatt cpd mytensor.tns -r 25 -t 4\n\nThis runs `splatt-cpd` on 'mytensor.tns' and finds a rank-25 CPD of the tensor.\nAdding '-t 4' instructs SPLATT to use four OpenMP threads during the\ncomputation. SPLATT will use all available CPU cores by default.  The matrix\nfactors are written to `modeN.mat` and lambda, the vector for scaling, is\nwritten to `lambda.mat`.\n\n\nDistributed-Memory Computation\n------------------------------\nSPLATT can optionally be built with support for distributed-memory systems via\nMPI. To add MPI support, simply add \"--with-mpi\" to the configuration step:\n\n    $ ./configure --with-mpi \u0026\u0026 make\n\nAfter building with MPI, `splatt-cpd` can be used as before. Careful\nconsideration should be given to the mapping of MPI ranks, because each SPLATT\nprocess will by default use all available CPU cores (`$OMP_MAX_THREADS`). We\nrecommend mapping one rank per CPU socket. The necessary parameters to `mpirun`\nvary based on the MPI implementation. For example, OpenMPI supports:\n\n### Example 3\n\n    $ mpirun --map-by ppr:1:socket -np 16 splatt cpd mytensor.tns -r 25 -t 8\n\nThis would fully utilize 16 sockets, each with 8 cores to compute a rank-25 CPD\nof `mytensor.tns`. To alternatively use one MPI rank per core:\n\n### Example 4\n\n    $ mpirun -np 128 splatt cpd mytensor.tns -r 25 -t 1\n\nThis would use 128 processes, with each using only one OpenMP thread.\n\n\nC/C++ API\n---------\nSPLATT provides a C API which is callable from C and C++. Installation not only\ninstalls the SPLATT executable, but also the shared library `libsplatt.so` and\nthe header `splatt.h`. To use the C API, include `splatt.h` and link against\nthe SPLATT library.\n\n### IO\nUnless otherwise noted, SPLATT expects tensors to be stored in the compressed\nsparse fiber (CSF) format. SPLATT provides two functions for forming a tensor\nin CSF:\n\n* `splatt_csf_load` reads a tensor from a file\n* `splatt_csf_convert` converts a tensor from coordinate format to CSF\n\n\n### Computation\n* `splatt_cpd` computes the CPD and returns a Kruskal tensor\n* `splatt_default_opts` allocates and returns an options array with defaults\n\n\n### Cleanup\nAll memory allocated by the SPLATT API should be freed by these functions:\n\n* `splatt_free_csf` deallocates a list of CSF tensors\n* `splatt_free_opts` deallocates a SPLATT options array\n* `splatt_free_kruskal` deallocates a Kruskal tensor\n\n### Example\nThe following is an example usage of the SPLATT API:\n\n    #include \u003csplatt.h\u003e\n\n    /* allocate default options */\n    double * cpd_opts = splatt_default_opts();\n\n    /* load the tensor from a file */\n    int ret;\n    splatt_idx_t nmodes;\n    splatt_csf_t * tt;\n    ret = splatt_csf_load(\"mytensor.tns\", \u0026nmodes, \u0026tt, cpd_opts);\n\n    /* do the factorization! */\n    splatt_kruskal_t factored;\n    ret = splatt_cpd_als(tt, 10, cpd_opts, \u0026factored);\n\n    /* do some processing */\n    for(splatt_idx_t m = 0; m \u003c nmodes; ++m) {\n      /* access factored.lambda and factored.factors[m] */\n    }\n\n    /* cleanup */\n    splatt_free_csf(tt, cpd_opts);\n    splatt_free_kruskal(\u0026factored);\n    splatt_free_opts(cpd_opts);\n\n\nPlease see `splatt.h` for further documentation of SPLATT structures and call\nsignatures.\n\n\nOctave/Matlab API\n-----------------\nSPLATT also provides an API callable from Octave and Matlab that wraps the C\nAPI. To compile the interface just enter the `matlab/` directory from either\nOctave or Matlab and call `make`.\n\n    \u003e\u003e cd matlab\n    \u003e\u003e make\n\n**NOTE:** Matlab uses a version of LAPACK/BLAS with 64-bit integers. Most\nLAPACK/BLAS libraries use 32-bit integers, and so SPLATT by default provides\n32-bit integers. You should either instruct Matlab to link against a matching\nlibrary, or configure SPLATT to also use 64-bit integers during configuration:\n\n    $ ./configure --blas-int=64\n\nNote that this may break usability of the SPLATT executable or API.\n\nSome Matlab versions have issues with linking to applications which use OpenMP\n(e.g., SPLATT) due to a limited amount of thread-local storage. This is a\nsystem limitation, not necessarily a software limitation. When calling SPLATT\nfrom Matlab, you may receive an error message:\n\n    dlopen: cannot load any more object with static TLS\n\nTwo workarounds for this issue are:\n1. Ensure that your OpenMP library is loaded first when starting Matlab.  The\nmost common OpenMP library is `libgomp.so.1`:\n\n        $ LD_PRELOAD=libgomp.so.1 matlab \n\n2. Disable OpenMP (at the cost of losing multi-threaded execution):\n\n        $ ./configure --no-openmp\n\n\nAfter compilation, the MEX files will be found in the current directory. You\ncan now call those functions directly:\n\n    \u003e\u003e KT = splatt_cpd('mytensor.tns', 25);\n\n`splatt_cpd` returns a structure with three fields:\n\n* `U` a cell array of the factor matrices\n* `lambda` the factor column norms absorbed into a vector\n* `fit` quality of the CPD defined by: 1 - (norm(residual) / norm(X))\n\nSPLATT also supports explicitly storing tensors in CSF form to avoid IO times\nduring successive factorizations,\n\n    \u003e\u003e X = splatt_load('mytensor.tns');\n    \u003e\u003e K25 = splatt_cpd(X, 25);\n    \u003e\u003e K50 = splatt_cpd(X, 50);\n\nSPLATT accepts non-default parameters via structures:\n\n    \u003e\u003e opts = struct('its', 100, 'tol', 1e-8);\n    \u003e\u003e XT = splatt_cpd(X, 25, opts);\n\nFinally, there are several SPLATT routines exposed for developing other tensor\noperations. SPLATT provides:\n\n* `splatt_mttkrp`\n* `splatt_norm`\n* `splatt_dim`\n* `splatt_innerprod`\n\nPlease see `help \u003ccmd\u003e` from an Octave/Matlab terminal or read \u003ccmd\u003e.m in the\n`matlab/` directory for more usage information.\n\n\nCiting\n------\nIf SPLATT has contributed to your research, please consider citing us:\n\n```\n  @misc{splattsoftware,\n    author = {Smith, Shaden and Karypis, George},\n    title = {{SPLATT: The Surprisingly ParalleL spArse Tensor Toolkit}},\n    howpublished = {\\url{http://cs.umn.edu/~splatt/}},\n    version = {1.1.1},\n    year = {2016},\n  }\n```\n\n\nLicensing\n---------\nSPLATT is released under the MIT License. Please see the 'LICENSE' file for\ndetails.\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShadenSmith%2Fsplatt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShadenSmith%2Fsplatt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShadenSmith%2Fsplatt/lists"}