From 5f2cb361caa02162e227576f794463de70004d4d Mon Sep 17 00:00:00 2001 From: vfisikop Date: Tue, 12 Mar 2024 17:45:22 +0200 Subject: [PATCH] Add JOSS paper --- .github/workflows/R-CMD-check-macOS.yml | 62 ------------------- .github/workflows/R-CMD-check-ubuntu.yml | 65 -------------------- .github/workflows/R-CMD-check-windows.yml | 61 ------------------- .github/workflows/cmake-clang.yml | 39 ------------ .github/workflows/cmake-examples.yml | 40 ------------- .github/workflows/cmake-gcc.yml | 38 ------------ .github/workflows/docs.yml | 27 --------- .github/workflows/draft_pdf.yml | 24 ++++++++ joss_paper/paper.bib => paper.bib | 0 joss_paper/paper.md => paper.md | 72 +++++++++++++++++++++++ 10 files changed, 96 insertions(+), 332 deletions(-) delete mode 100644 .github/workflows/R-CMD-check-macOS.yml delete mode 100644 .github/workflows/R-CMD-check-ubuntu.yml delete mode 100644 .github/workflows/R-CMD-check-windows.yml delete mode 100644 .github/workflows/cmake-clang.yml delete mode 100644 .github/workflows/cmake-examples.yml delete mode 100644 .github/workflows/cmake-gcc.yml delete mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/draft_pdf.yml rename joss_paper/paper.bib => paper.bib (100%) rename joss_paper/paper.md => paper.md (55%) diff --git a/.github/workflows/R-CMD-check-macOS.yml b/.github/workflows/R-CMD-check-macOS.yml deleted file mode 100644 index b1ac281c3..000000000 --- a/.github/workflows/R-CMD-check-macOS.yml +++ /dev/null @@ -1,62 +0,0 @@ -############################################################################## -# GitHub Actions Workflow to test the R interface of volesti -# -# Copyright (c) 2020 Vissarion Fisikopoulos -# -# Licensed under GNU LGPL.3, see LICENCE file -############################################################################## - -on: [push, pull_request] - -name: R-CMD-check-macOS - -jobs: - R-CMD-check: - runs-on: ${{ matrix.config.os }} - - name: ${{ matrix.config.os }} (${{ matrix.config.r }}) - - strategy: - fail-fast: false - matrix: - config: - - {os: macOS-latest, r: '4.1.2'} -# - {os: macOS-latest, r: 'devel'} # Error in library(devtools) : there is no package called ‘devtools’ - - {os: macOS-latest, r: 'release'} - - env: - R_REMOTES_NO_ERRORS_FROM_WARNINGS: true - RSPM: ${{ matrix.config.rspm }} - GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} - - steps: - - uses: actions/checkout@v3 - - - uses: r-lib/actions/setup-r@v2 - with: - r-version: ${{ matrix.config.r }} - - - uses: r-lib/actions/setup-pandoc@v2 - - - name: Install dependencies - run: Rscript -e "install.packages(c('devtools', dependencies=TRUE))" -e "install.packages(c('rcmdcheck', 'devtools', 'Rcpp', 'RcppEigen', 'BH', 'testthat', 'downloader', 'xfun'))"; - - - name: Checkout Rvolesti repository - run: git clone https://github.com/GeomScale/Rvolesti.git; - - - name: Upgrade with current develop of volesti - run: cp -rf include Rvolesti/src/volesti; - cp -rf external Rvolesti/src; - - - name: Check - env: - _R_CHECK_CRAN_INCOMING_REMOTE_: false - run: cd Rvolesti/; - Rscript -e "library(rcmdcheck)" -e "rcmdcheck::rcmdcheck(args = c('--no-manual'), error_on = 'warning', check_dir = 'check')" - - - name: Upload check results - if: failure() - uses: actions/upload-artifact@v2 - with: - name: ${{ runner.os }}-r${{ matrix.config.r }}-results - path: check diff --git a/.github/workflows/R-CMD-check-ubuntu.yml b/.github/workflows/R-CMD-check-ubuntu.yml deleted file mode 100644 index 753ee114a..000000000 --- a/.github/workflows/R-CMD-check-ubuntu.yml +++ /dev/null @@ -1,65 +0,0 @@ -############################################################################## -# GitHub Actions Workflow to test the R interface of volesti -# -# Copyright (c) 2020 Vissarion Fisikopoulos -# -# Licensed under GNU LGPL.3, see LICENCE file -############################################################################## - -on: [push, pull_request] - -name: R-CMD-check-ubuntu - -jobs: - R-CMD-check: - runs-on: ${{ matrix.config.os }} - - name: ${{ matrix.config.os }} (${{ matrix.config.r }}) - - strategy: - fail-fast: false - matrix: - config: - - {os: ubuntu-latest, r: 'devel'} - - {os: ubuntu-latest, r: 'release'} - - {os: ubuntu-20.04, r: 'devel'} - - {os: ubuntu-20.04, r: 'release'} - - env: - R_REMOTES_NO_ERRORS_FROM_WARNINGS: true - RSPM: ${{ matrix.config.rspm }} - GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} - - steps: - - uses: actions/checkout@v3 - - run: sudo apt-get update || true; - sudo apt install build-essential libcurl4-gnutls-dev libxml2-dev libssl-dev libgit2-dev libfontconfig1-dev libharfbuzz-dev libfribidi-dev; - - - uses: r-lib/actions/setup-r@v2 - with: - r-version: ${{ matrix.config.r }} - - - uses: r-lib/actions/setup-pandoc@v2 - - - name: Install dependencies - run: Rscript -e "install.packages(c('testthat', 'pkgload', 'rcmdcheck', 'devtools', 'Rcpp', 'RcppEigen', 'BH', 'downloader', 'xfun', dependencies=TRUE))"; - - - name: Checkout Rvolesti repository - run: git clone https://github.com/GeomScale/Rvolesti.git; - - - name: Upgrade with current develop of volesti - run: cp -rf include Rvolesti/src/volesti; - cp -rf external Rvolesti/src; - - - name: Check - env: - _R_CHECK_CRAN_INCOMING_REMOTE_: false - run: cd Rvolesti/; - Rscript -e "library(rcmdcheck)" -e "rcmdcheck::rcmdcheck(args = c('--no-manual'), error_on = 'warning', check_dir = 'check')" - - - name: Upload check results - if: failure() - uses: actions/upload-artifact@v2 - with: - name: ${{ runner.os }}-r${{ matrix.config.r }}-results - path: check diff --git a/.github/workflows/R-CMD-check-windows.yml b/.github/workflows/R-CMD-check-windows.yml deleted file mode 100644 index 97e725aa0..000000000 --- a/.github/workflows/R-CMD-check-windows.yml +++ /dev/null @@ -1,61 +0,0 @@ -############################################################################## -# GitHub Actions Workflow to test the R interface of volesti -# -# Copyright (c) 2020 Vissarion Fisikopoulos -# -# Licensed under GNU LGPL.3, see LICENCE file -############################################################################## - -on: [push, pull_request] - -name: R-CMD-check-windows - -jobs: - R-CMD-check: - runs-on: ${{ matrix.config.os }} - - name: ${{ matrix.config.os }} (${{ matrix.config.r }}) - - strategy: - fail-fast: false - matrix: - config: -# - {os: windows-latest, r: 'devel'} # Error in library(devtools) : there is no package called ‘devtools’ - - {os: windows-latest, r: 'release'} - - env: - R_REMOTES_NO_ERRORS_FROM_WARNINGS: true - RSPM: ${{ matrix.config.rspm }} - GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} - - steps: - - uses: actions/checkout@v3 - - - uses: r-lib/actions/setup-r@v2 - with: - r-version: ${{ matrix.config.r }} - - - uses: r-lib/actions/setup-pandoc@v2 - - - name: Install dependencies - run: Rscript -e "install.packages(c('devtools', dependencies=TRUE))" -e "install.packages(c('rcmdcheck', 'devtools', 'Rcpp', 'RcppEigen', 'BH', 'testthat', 'downloader', 'xfun'))" - - - name: Checkout Rvolesti repository - run: git clone https://github.com/GeomScale/Rvolesti.git; - - - name: Upgrade with current develop of volesti - run: cp -r -fo include Rvolesti/src/volesti; - cp -r -fo external Rvolesti/src; - - - name: Check - env: - _R_CHECK_CRAN_INCOMING_REMOTE_: false - run: cd Rvolesti/; - Rscript -e "library(rcmdcheck)" -e "rcmdcheck::rcmdcheck(args = c('--no-manual'), error_on = 'warning', check_dir = 'check')" - - - name: Upload check results - if: failure() - uses: actions/upload-artifact@v2 - with: - name: ${{ runner.os }}-r${{ matrix.config.r }}-results - path: check diff --git a/.github/workflows/cmake-clang.yml b/.github/workflows/cmake-clang.yml deleted file mode 100644 index 520b33159..000000000 --- a/.github/workflows/cmake-clang.yml +++ /dev/null @@ -1,39 +0,0 @@ -############################################################################## -# GitHub Actions Workflow for volesti to build tests with Clang -# -# Copyright (c) 2020-2022 Vissarion Fisikopoulos -# -# Licensed under GNU LGPL.3, see LICENCE file -############################################################################## -name: cmake-clang - -on: [push, pull_request] - -jobs: - build: - name: ${{ matrix.config.os }} - ${{ matrix.config.compiler }} - strategy: - fail-fast: false - matrix: - config: - - {os: ubuntu-22.04, compiler_pkg: clang-11, compiler: clang++-11} - - {os: ubuntu-22.04, compiler_pkg: clang-12, compiler: clang++-12} - - {os: ubuntu-22.04, compiler_pkg: clang-13, compiler: clang++-13} - - {os: ubuntu-22.04, compiler_pkg: clang-14, compiler: clang++-14} - #- {os: ubuntu-22.04, compiler_pkg: clang-15, compiler: clang++-15} - - {os: ubuntu-20.04, compiler_pkg: clang-8, compiler: clang++-8} - - {os: ubuntu-20.04, compiler_pkg: clang-9, compiler: clang++-9} - - {os: ubuntu-20.04, compiler_pkg: clang-10, compiler: clang++-10} - - {os: ubuntu-20.04, compiler_pkg: clang-11, compiler: clang++-11} - - {os: ubuntu-20.04, compiler_pkg: clang-12, compiler: clang++-12} - runs-on: ${{ matrix.config.os }} - steps: - - uses: actions/checkout@v1 - - run: sudo apt-get update || true; - sudo apt-get install ${{ matrix.config.compiler_pkg }} lp-solve libopenblas-dev; - rm -rf build; - mkdir build; - cd build; - cmake -D CMAKE_CXX_COMPILER=${{ matrix.config.compiler }} -D CMAKE_CXX_FLAGS=-fsanitize=memory -D CMAKE_CXX_FLAGS=-fsanitize=undefined -D CMAKE_CXX_FLAGS=-g -D DISABLE_NLP_ORACLES=ON -D USE_MKL=OFF ../test; - make; - ctest --verbose; \ No newline at end of file diff --git a/.github/workflows/cmake-examples.yml b/.github/workflows/cmake-examples.yml deleted file mode 100644 index b7784fa30..000000000 --- a/.github/workflows/cmake-examples.yml +++ /dev/null @@ -1,40 +0,0 @@ -############################################################################## -# GitHub Actions Workflow for volesti to build tests with GCC -# -# Copyright (c) 2020-2022 Vissarion Fisikopoulos -# -# Licensed under GNU LGPL.3, see LICENCE file -############################################################################## -name: cmake-examples - -on: [push, pull_request] - -jobs: - build: - name: ${{ matrix.config.os }} - ${{ matrix.config.compiler }} - strategy: - fail-fast: false - matrix: - config: - - {os: ubuntu-22.04, compiler_pkg: clang-11, compiler: clang++-11} - - {os: ubuntu-22.04, compiler_pkg: g++-11, compiler: g++-11} - runs-on: ${{ matrix.config.os }} - steps: - - uses: actions/checkout@v1 - - run: sudo apt-get update || true; - sudo apt-get install ${{ matrix.config.compiler_pkg }} lp-solve libomp-dev libopenblas-dev libarpack2-dev; - - name: Build examples - run: | - cd examples - for dir in */; do - if [ "$dir" != "EnvelopeProblemSOS/" ] && [ "$dir" != "python_utilities/" ]; then - echo - echo "Building examples in $dir ....................." - cd "$dir" - mkdir build && cd build - cmake -DCMAKE_CXX_COMPILER=${{ matrix.config.compiler }} -DUSE_MKL=OFF .. - make - cd ../.. - fi - done - diff --git a/.github/workflows/cmake-gcc.yml b/.github/workflows/cmake-gcc.yml deleted file mode 100644 index f18e358ac..000000000 --- a/.github/workflows/cmake-gcc.yml +++ /dev/null @@ -1,38 +0,0 @@ -############################################################################## -# GitHub Actions Workflow for volesti to build tests with GCC -# -# Copyright (c) 2020-2021 Vissarion Fisikopoulos -# -# Licensed under GNU LGPL.3, see LICENCE file -############################################################################## -name: cmake-gcc - -on: [push, pull_request] - -jobs: - build: - name: ${{ matrix.config.os }} - ${{ matrix.config.compiler }} - strategy: - fail-fast: false - matrix: - config: - - {os: ubuntu-22.04, compiler: g++-9} - - {os: ubuntu-22.04, compiler: g++-10} - - {os: ubuntu-22.04, compiler: g++-11} - - {os: ubuntu-22.04, compiler: g++-12} - #- {os: ubuntu-22.04, compiler: g++-13} - - {os: ubuntu-20.04, compiler: g++-7} - - {os: ubuntu-20.04, compiler: g++-8} - - {os: ubuntu-20.04, compiler: g++-9} - - {os: ubuntu-20.04, compiler: g++-10} - runs-on: ${{ matrix.config.os }} - steps: - - uses: actions/checkout@v1 - - run: sudo apt-get update || true; - sudo apt-get install ${{ matrix.config.compiler }} lp-solve libopenblas-dev; - rm -rf build; - mkdir build; - cd build; - cmake -D CMAKE_CXX_COMPILER=${{ matrix.config.compiler }} -D DISABLE_NLP_ORACLES=ON -D USE_MKL=OFF ../test; - make; - ctest --verbose; diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index fca7ede90..000000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Docs -on: [push, pull_request] - -jobs: - notebooks: - name: "Build the docs" - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - - name: Set up Python - uses: actions/setup-python@v2 - with: - python-version: 3.8 - - - name: Install dependencies - run: | - sudo apt-get install doxygen - python -m pip install -U pip - python -m pip install -r docs/requirements.txt - - - name: Build the docs - run: | - python -m pip install -U setuptools - python -m pip install -U pillow mock alabaster commonmark recommonmark sphinx sphinx-rtd-theme readthedocs-sphinx-ext - cd docs - python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html diff --git a/.github/workflows/draft_pdf.yml b/.github/workflows/draft_pdf.yml new file mode 100644 index 000000000..1d7dc44e4 --- /dev/null +++ b/.github/workflows/draft_pdf.yml @@ -0,0 +1,24 @@ +name: Draft PDF +on: [push] + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper.md + - name: Upload + uses: actions/upload-artifact@v4 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper.pdf diff --git a/joss_paper/paper.bib b/paper.bib similarity index 100% rename from joss_paper/paper.bib rename to paper.bib diff --git a/joss_paper/paper.md b/paper.md similarity index 55% rename from joss_paper/paper.md rename to paper.md index 06b30ef4a..f618100b0 100644 --- a/joss_paper/paper.md +++ b/paper.md @@ -1,10 +1,18 @@ --- +<<<<<<< HEAD title: 'volesti: C++ library for sampling and volume computation on convex bodies' +======= +title: 'volesti: A C++ library for sampling and volume computation on convex bodies' +>>>>>>> 7a9d674 (Add JOSS paper) tags: - C++ - geometry - randomization +<<<<<<< HEAD - Monte-Carlo methods +======= + - Monte Carlo methods +>>>>>>> 7a9d674 (Add JOSS paper) - convexity authors: - name: Apostolos Chalkis @@ -26,7 +34,11 @@ affiliations: index: 1 - name: Quantagonia index: 2 +<<<<<<< HEAD - name: Inria Paris and IMJ-PRG, Sorbonne Universit\`e +======= + - name: Inria Paris and IMJ-PRG, Sorbonne Universit\'e +>>>>>>> 7a9d674 (Add JOSS paper) index: 3 - name: GeomScale index: 4 @@ -44,6 +56,7 @@ bodies are fundamental operations that appear in optimization, finance, engineering, artificial intelligence, and machine learning. We present `volesti`, a C++ library that delivers efficient implementations of state-of-the-art, mainly randomized, algorithms to sample from general logconcave distributions. +<<<<<<< HEAD Based on these routines can estimate the volume of convex bodies in high dimensions, round them and also compute multidimensional integrals over them. The backbone of our library consists of Monte-Carlo algorithms, @@ -52,18 +65,34 @@ high-dimensional statistical tests to certify and verify the output. The focus of `volesti`' is scalability in high dimensions, that, depending on the problem at hand, could be in the order of hundreds or thousands dimension. +======= +Based on these routines, we can estimate the volume of convex bodies in high dimensions, +round them, and compute multidimensional integrals over them. +The backbone of our library consists of Monte Carlo algorithms, +which are randomized algorithms, the output of which can be incorrect with (usually very small) error probability; thus, we also provide several +high-dimensional statistical tests to certify and verify the output. + +The focus of `volesti`' is scalability in high dimensions, +that, depending on the problem at hand, could range from hundreds to thousands of dimensions. +>>>>>>> 7a9d674 (Add JOSS paper) Another novelty is the ability to handle a variety of different inputs for the constrained support of the various distributions. `volesti` supports three different types of polyhedra [@Ziegler:1995], spectrahedra [@Ramana:1999] and general non-linear convex objects. +<<<<<<< HEAD `volesti` relies on `Eigen` library [@eigen] for linear algebra but also support `MKL` optimizations [@mkl]. There are R [@Chalkis:2021] and Python [@Chalkis_dingo:2023] interfaces available; alas not all C++ functionality is available in through these interfaces. +======= +`volesti` relies on `Eigen` library [@eigen] for linear algebra but also supports `MKL` optimizations [@mkl]. +There are R [@Chalkis:2021] and Python [@Chalkis_dingo:2023] interfaces available. +>>>>>>> 7a9d674 (Add JOSS paper) # Statement of need High-dimensional sampling from multivariate distributions with Markov Chain Monte Carlo (MCMC) +<<<<<<< HEAD algorithms is a fundamental problem with many applications in the whole spectrum of science and engineering [@Iyengar:1988; @Somerville:1998; @Genz:2009; @Schellenberger:2009]. In particular, multivariate integration over a convex set @@ -117,5 +146,48 @@ but also to more theoretical and mathematical challenges, like the computation o We would like to thank the contributors to the `volesti` library for their valuable contributions and feedback. +======= +algorithms is a fundamental problem with many applications in science and engineering [@Iyengar:1988; @Somerville:1998; @Genz:2009; @Schellenberger:2009]. +In particular, multivariate integration over a convex set as well as the volume approximation of convex sets have garnered significant attention from theorists and engineers over the last decades. +Nevertheless, these problems are computationally hard for general dimensions [@Dyer:1988]. +MCMC algorithms made remarkable progress and their use allowed us to efficiently tackle the problems of sampling and volume estimation of convex bodies in theory, +by the introduction of (rigorous) theoretical guarantees [@Chen:2018; @Lee:2018; +@Mangoubi:2019]. +Unfortunately, these theoretical guarantees of the MCMC algorithms +do not extend in a straightforward manner to efficient implementations able to attack problems coming from real-life computations. +Therefore, we witnessed the birth of efficient in practice MCMC algorithm +that relax the theoretical guarantees and employ new algorithmic and statistical techniques +to be amenable to efficient implementations. +Remarkably, these algorithms, and the corresponding implementations, +also meet the requirements for high accuracy results +[@Emiris:2014; @Cousins:2015; @Chalkis_volume:2023; @Kook:2022]; +however several existing published methods are available as part of propertiary packages (MATLAB) [@Cousins:2015; @Kook:2022]. + +Our open-source package -- volesti -- offers all of the aforementioned functionality, together with the support of sampling from general log-concave densities @Chalkis_hmc:2023, and uniform sampling from spectrahedra @Chalkis_spectra:2022. + +Our implementation supports: +1. support various sampling techniques based on geometric walks, roughly speaking these are a continuous version of MCMC algorithms, such as Billard walk, Hamiltonian walk and others, +2. give the user the ability to sample from various distributions, like uniform, exponential, Gaussian, and general log-concave densities, +3. allows to consider the distributions constrained in various convex domains, such as hypercubes, zonotopes, general polytopes (defined either as a set of linear inequalities or as a convex hull of a pointset), spectrahedra (feasible sets of semidefinite programs), and, +4. can perform volume computations, integration, and solve problems from real life applications in very high dimensions. + +# Impact + +`volesti` has been used extensively in various research and engineering projects coauthored by the authors of this paper. +In particular, for the problem of sampling the flux space of metabolic networks +we were able to sample from the most complicated human metabolic network accessible today, Recon3D [@cftz-socg021], +used to model financial crises [@ccef-crises-j], +to detect low volatility anomalies in stock markets [@bcft-aistats-23], + to introduce randomized control in asset pricing and portfolio performance evaluation [@bcft-arxiv-24]), but also to sample from (and compute the volume of) spectrahedra [@Chalkis_spectra:2022], the feasible regions of semidefinite programs. + +Even more, `volesti` has been used by other research teams in conducting research in electric power systems [@Venzke:2019], for problems in probabilistic inference [@Spallitta:2024], +to perform resource analysis on programs [@pham-phd-2024]; +but also for more theoretical and mathematical challenges, like the computation of topological invariants [@co-alenex-2021], and persistent homology [@vm-fods-2022]. + +# Acknowledgements + +We would like to thank the contributors to the `volesti` library for their valuable contributions and feedback. +MP was partially supported by a Cornell University Fellowship, a grant from the A.G. Leventis Foundation, a grant from the Gerondelis Foundation, and a LinkedIn Ph.D. Fellowship. +>>>>>>> 7a9d674 (Add JOSS paper) # References