-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
GitHub CI Documentation builder
committed
Jan 8, 2025
1 parent
5a205d9
commit 5a9314f
Showing
56 changed files
with
2,816 additions
and
2,594 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,179 @@ | ||
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | ||
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> | ||
| <head> | ||
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> | ||
| <meta http-equiv="X-UA-Compatible" content="IE=11"/> | ||
| <meta name="generator" content="Doxygen 1.9.8"/> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1"/> | ||
| <title>Gyselalib++: Getting Started with Gyselalib++</title> | ||
| <link href="tabs.css" rel="stylesheet" type="text/css"/> | ||
| <script type="text/javascript" src="jquery.js"></script> | ||
| <script type="text/javascript" src="dynsections.js"></script> | ||
| <link href="navtree.css" rel="stylesheet" type="text/css"/> | ||
| <script type="text/javascript" src="resize.js"></script> | ||
| <script type="text/javascript" src="navtreedata.js"></script> | ||
| <script type="text/javascript" src="navtree.js"></script> | ||
| <link href="search/search.css" rel="stylesheet" type="text/css"/> | ||
| <script type="text/javascript" src="search/searchdata.js"></script> | ||
| <script type="text/javascript" src="search/search.js"></script> | ||
| <script type="text/javascript"> | ||
| /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ | ||
| $(document).ready(function() { init_search(); }); | ||
| /* @license-end */ | ||
| </script> | ||
| <script type="text/x-mathjax-config"> | ||
| MathJax.Hub.Config({ | ||
| extensions: ["tex2jax.js"], | ||
| jax: ["input/TeX","output/HTML-CSS"], | ||
| }); | ||
| </script> | ||
| <script type="text/javascript" async="async" src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js"></script> | ||
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> | ||
| </head> | ||
| <body> | ||
| <div id="top"><!-- do not remove this div, it is closed by doxygen! --> | ||
| <div id="titlearea"> | ||
| <table cellspacing="0" cellpadding="0"> | ||
| <tbody> | ||
| <tr id="projectrow"> | ||
| <td id="projectlogo"><img alt="Logo" src="logo.png"/></td> | ||
| <td id="projectalign"> | ||
| <div id="projectname">Gyselalib++ | ||
| </div> | ||
| </td> | ||
| <td> <div id="MSearchBox" class="MSearchBoxInactive"> | ||
| <span class="left"> | ||
| <span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span> | ||
| <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S" | ||
| onfocus="searchBox.OnSearchFieldFocus(true)" | ||
| onblur="searchBox.OnSearchFieldFocus(false)" | ||
| onkeyup="searchBox.OnSearchFieldChange(event)"/> | ||
| </span><span class="right"> | ||
| <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a> | ||
| </span> | ||
| </div> | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
| </div> | ||
| <!-- end header part --> | ||
| <!-- Generated by Doxygen 1.9.8 --> | ||
| <script type="text/javascript"> | ||
| /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ | ||
| var searchBox = new SearchBox("searchBox", "search/",'.html'); | ||
| /* @license-end */ | ||
| </script> | ||
| </div><!-- top --> | ||
| <div id="side-nav" class="ui-resizable side-nav-resizable"> | ||
| <div id="nav-tree"> | ||
| <div id="nav-tree-contents"> | ||
| <div id="nav-sync" class="sync"></div> | ||
| </div> | ||
| </div> | ||
| <div id="splitbar" style="-moz-user-select:none;" | ||
| class="ui-resizable-handle"> | ||
| </div> | ||
| </div> | ||
| <script type="text/javascript"> | ||
| /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ | ||
| $(document).ready(function(){initNavTree('docs_getting_started.html',''); initResizable(); }); | ||
| /* @license-end */ | ||
| </script> | ||
| <div id="doc-content"> | ||
| <!-- window showing the filter options --> | ||
| <div id="MSearchSelectWindow" | ||
| onmouseover="return searchBox.OnSearchSelectShow()" | ||
| onmouseout="return searchBox.OnSearchSelectHide()" | ||
| onkeydown="return searchBox.OnSearchSelectKey(event)"> | ||
| </div> | ||
|
|
||
| <!-- iframe showing the search results (closed by default) --> | ||
| <div id="MSearchResultsWindow"> | ||
| <div id="MSearchResults"> | ||
| <div class="SRPage"> | ||
| <div id="SRIndex"> | ||
| <div id="SRResults"></div> | ||
| <div class="SRStatus" id="Loading">Loading...</div> | ||
| <div class="SRStatus" id="Searching">Searching...</div> | ||
| <div class="SRStatus" id="NoMatches">No Matches</div> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| </div> | ||
|
|
||
| <div><div class="header"> | ||
| <div class="headertitle"><div class="title">Getting Started with Gyselalib++</div></div> | ||
| </div><!--header--> | ||
| <div class="contents"> | ||
| <div class="textblock"><p>Welcome to the gyselalib++ project! This guide is designed to help new developers understand how to get started with the project. Please bear in mind that developers unfamiliar with C++ will not find the answers to all their questions in the documentation. While we aim to provide documentation where relevant, this is not a replacement for foundational C++ knowledge; instead, it focuses on the specific challenges and paradigms relevant to gyselalib++. If you encounter unfamiliar keywords or concepts in the code, we recommend looking them up online as a first step. This will help you build a deeper understanding and use your time more effectively before seeking further assistance.</p> | ||
| <hr /> | ||
| <h1><a class="anchor" id="docs_getting_started__Understanding_Functional_Programming_in_Gyselalibxx"></a> | ||
| Understanding Functional Programming in Gyselalib++</h1> | ||
| <p>There are multiple coding paradigms possible when writing code in C++. Two of the most common are object-oriented programming and functional programming. You may be familiar with object-oriented programming however gyselalib++ uses functional programming.</p> | ||
| <h3><a class="anchor" id="autotoc_md22"></a> | ||
| Key Difference: Functional vs. Object-Oriented Programming (OOP)</h3> | ||
| <p><b>Object-Oriented Programming (OOP)</b> is built around the concept of objects that encapsulate data and behavior. Developers used to OOP often think in terms of classes, inheritance, and polymorphism. While these are powerful concepts, they are not central to how gyselalib++ is structured. This is notably because inheritance, and polymorphism are often incompatible with GPU programming.</p> | ||
| <p><b>Functional Programming (FP)</b> aims to make code more readable by making it more obvious where data is modified. This is done by separating data storage from operators. This way, data can never be modified inside its class without passing through an operator. In our code the functional programming paradigm was chosen as it allows us to write the code in a way which more closely resembles the equations.</p> | ||
| <h3><a class="anchor" id="autotoc_md23"></a> | ||
| Operators and Data Structures</h3> | ||
| <p>When using functional programming classes fit into one of two groups:</p> | ||
| <ul> | ||
| <li><b>Data Structures</b>:<ul> | ||
| <li>Serve as containers for data, often passed into operators for processing.</li> | ||
| <li>Avoid embedding behavior directly into data structures; instead, let operators handle transformations.</li> | ||
| </ul> | ||
| </li> | ||
| <li><b>Operators</b>:<ul> | ||
| <li>Should implement an <code>operator()</code> method, allowing them to be used as callable objects.</li> | ||
| <li>Their internal variables should remain constant to align with functional programming principles.</li> | ||
| <li>Break problems into small, composable functions. Avoid the temptation to design large, monolithic classes.</li> | ||
| <li>Can be thought of as a function. Classes are used instead so the functions called by this function can be decided at compile time.</li> | ||
| </ul> | ||
| </li> | ||
| </ul> | ||
| <p>By separating operators (behavior) from data structures (data), you ensure clarity, reusability, and better adherence to the functional programming style.</p> | ||
| <p>For example consider the case of a semi-Lagrangian advection. The operator is similar to a function which modifies a data structure containing the distribution function. By using a class the method used to interpolate the function (e.g. spline interpolation or <a class="el" href="classLagrange.html" title="A class which implements Lagrange polynomials.">Lagrange</a> interpolation) can be specified without duplicating code.</p> | ||
| <hr /> | ||
| <h1><a class="anchor" id="docs_getting_started__Navigating_the_Gyselalibxx_Codebase"></a> | ||
| Navigating the Gyselalib++ Codebase</h1> | ||
| <p>The gyselalib++ codebase is organised into several folders. The main folders of interest are:</p><ul> | ||
| <li><b>src/</b> : This folder contains the source code for the library. It contains folders grouping the code by subject. The <code>src/</code> folder and each sub-folder contains a <code>README.md</code> detailing its contents. It is simple to navigate within this documentation : <a class="el" href="src.html">Gyselalib++ contents</a><ul> | ||
| <li><b>geometry...</b> : The <code>src/</code> folder contains sub-folders whose names begin with <code>geometry</code>. These sub-folders contain code which is specific to a given geometry. Each geometry is defined by the dimensions on which its equations are defined. In these folders you will also find sub-folders grouping the code by subject. Each <code>geometry...</code> folder will contain a folder called <code>geometry</code> containing a file <code>geometry.hpp</code>. This file contains type aliases which are useful for this geometry. This includes the definition of the classes representing the dimensions. If a <code>geometry.hpp</code> is included in a file then this file can only be used for that specific geometry. Therefore files in a <code>geometry...</code> folder cannot be used for other geometries even if the two appear to be compatible at first glance (e.g. files from the <code>geometryRTheta</code> folder cannot be used for the <code>geometryAxi</code> simulations, files from the <code>geometryXVx</code> folder cannot be used for the <code>geometryXYVxVy</code> simulations).</li> | ||
| </ul> | ||
| </li> | ||
| <li><b>tests/</b> : This folder contains the unit tests for the library. The folder structure is similar to that found in the <code>src/</code> folder.</li> | ||
| <li><b>simulations/</b> : This folder contains examples of simulations. In order to use the gyselalib++ library for research applications we usually create a new repository which contains this repository as a sub-module, however there are still some simulations hosted in this repository. This is notably the case for simulations which have known properties that can be used as end-to-end tests. For example the Landau damping case.</li> | ||
| </ul> | ||
| <hr /> | ||
| <h1><a class="anchor" id="docs_getting_started__Recommended_Steps_for_Getting_Started"></a> | ||
| Recommended Steps for Getting Started</h1> | ||
| <ol type="1"> | ||
| <li><b>Familiarize yourself with DDC:</b><ul> | ||
| <li>Gyselalib++ relies heavily on <a href="https://ddc.mdls.fr/">DDC (Discrete Domain Decomposition Library)</a> for data management. Understanding its usage is key to contributing effectively.</li> | ||
| <li>See our detailed guide on DDC integration: <a class="el" href="docs_DDC_in_gyselalibxx.html">Using DDC in Gyselalibxx</a>.</li> | ||
| </ul> | ||
| </li> | ||
| <li><b>Build the project:</b><ul> | ||
| <li>Follow the build instructions in the repository's README.</li> | ||
| <li>More detailed instructions especially instructions for specific systems like the CEA's persee can be found in the toolchain documentation: <a class="el" href="toolchains.html">Pre-made build settings</a>.</li> | ||
| </ul> | ||
| </li> | ||
| <li><b>Identify a simple task:</b><ul> | ||
| <li>Start with a small, well-scoped issue to familiarize yourself with the contribution process and code review workflow.</li> | ||
| </ul> | ||
| </li> | ||
| </ol> | ||
| <hr /> | ||
| <p>We hope this guide sets you on the right path to contributing to gyselalib++. Happy coding! </p> | ||
| </div></div><!-- contents --> | ||
| </div><!-- PageDoc --> | ||
| </div><!-- doc-content --> | ||
| <!-- start footer part --> | ||
| <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> | ||
| <ul> | ||
| <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li> | ||
| </ul> | ||
| </div> | ||
| </body> | ||
| </html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.