lymph
Documentation

Table of Contents

lymph (discontinuous poLYtopal methods for Multi-PHysics) is an open-source Matlab code for the simulation of multiphyisics differential problems. lymph is developed at MOX (The Laboratory for Modeling and Scientific Computing, Department of Mathematics) at Politecnico di Milano. The development of lymph is part of the activities of the project NEMESIS (https://erc-nemesis.eu, P.I.@PoliMI Paola F. Antonietti) and involves the following research group:

Maintainers

Installation

  1. Download and install the MATLAB software.
  2. Clone the lymph repository from here or alternatively use the git-command 
      clone git@bitbucket.org:lymph/lymph.git
  3. Run the script ImportLymphPaths.m contained in the lymph folder.

The source code and additional information can be found here.

Library structure

  • Core Contains common tools for discontinuous Galerkin methods on polygonal grids.
    • FEspace Dof maps and evaluation of basis functions on quadrature points.
    • MeshGeneration
      • PolyMesh Generation of a polytopal mesh based on PolyMesher and functions to compute neigboring elements/faces.
    • PostProcessing Post-processing tools, to plot and export output.
    • Quadrature Quadrature rules.
    • Utilities Functions used extensively throughout the library.
  • Physics Contains code to set-up and discretize specific PDE models.
    • ImportLymphPaths.m Set up the environment paths to use lymph: call ImportLymphPaths in your Run*.m file (see below).
    • One folder for each specific PDE model (named MYPHYSICS below), all sharing the following structure (see the Heat folder for an example):
      • Run*MYPHYSICS.m Callable script(s) to initialize lymph, set up the I/O parameters of the simulation, and launch the execution of a simulation (see also next point). Multiple files with such name can be present, e.g. to run single simulations, convergence analysis, etc. This/these file(s) must include the following lines: 
        %% Import lymph and add path related to this physics.
run("../ImportLymphPaths.m")
MyPhysicsPath = pwd;
addpath(genpath(fullfile(ProblemPath,'Assembly')));
addpath(genpath(fullfile(ProblemPath,'InputData')));
... and same for all other directories related to MYPHYSICS ...

%% Simulation - Setup
run("../RunSetup.m")
      • MainFunctions Folder with actual main function of a simulation, launched by Run*MYPHYSICS.m.
      • Assembly Folder with functions to assemble the system of interest.
      • Error Folder with functions ompute error w.r.t. an exact solution (given in InputData).
      • InputData Folder with parameters of the model and of its discretization.
      • PostProcessing Folder with physics-specific functions for post-processing: see also ../Core/PostProcessing for physics-independent functions (e.g. conversion to VTK format).
      • Other folders containing utilities and functions to address specific issues of a physics solver.
      • The folders related to lymph tutorials distributed with the current release contain also a Doxygen folder with their own documentation.
    • RunSetup.m To configure speficic run. In particular one can select the following options: 
      % Plot polygonal mesh
Setup.isPlotMesh = 0;

% Save VTK polygonal mesh
Setup.isSaveVTKMesh = 0;

% Plot solution
Setup.isPlotSolution = 0;

% Save solution in .mat format
Setup.isSaveSolution = 0;
Setup.OutFolder = 'Output';

% Save solution for Paraview in .csv or .vtk format
Setup.isSaveCSV    = 0;
Setup.isSaveVTK    = 0;
Setup.OutFolderVTK = 'OutputVTK';

% Compute errors
Setup.isError = 1;

License and Funding

  • You can cite lymph by this documentation site (https://lymph.bitbucket.io/) and the following preprint:

    P.F. Antonietti, S. Bonetti, M. Botti, M. Corti, I. Fumagalli, I. Mazzieri (2024). lymph: discontinuous poLYtopal methods for Multi-PHysics differential problems. arXiv preprint arXiv:2401.13376. https://doi.org/10.48550/arXiv.2401.13376

    lymph is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. lymph is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with lymph. If not, see http://www.gnu.org/licenses/.

  • Mesh generation in lymph is based on PolyMesher (version v1.1), a library available at http://paulino.princeton.edu/software.html for educational or academic use only. All rights of reproduction or distribution of PolyMesher in any form are reserved. The release paper of PolyMesher is the following:
    C. Talischi, G.H. Paulino, A. Pereira, I.F.M. Menezes (2012). "PolyMesher: A general-purpose mesh generator for polygonal elements written in Matlab", Structural and Multidisciplinary Optimization, DOI: 10.1007/s00158-011-0706-z

  • Doxygen-based documentation was possible thanks to m2cpp.pl, available as
    Fabrice (2023). "Using Doxygen with Matlab" (https://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab), MATLAB Central File Exchange. Retrieved November 24, 2023.
    Copyright (c) 2009, Fabrice. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The developers of lymph acknowledge the support of