Skip to content

Commit

Permalink
Merge pull request #245 from mpotse/develop
Browse files Browse the repository at this point in the history 
Develop
  • Loading branch information
@Algiane
Algiane authored Mar 4, 2024
2 parents a9e4fd6 + 068be52 commit 5788cf5
Show file tree
Hide file tree
Showing 140 changed files with 2,920 additions and 2,549 deletions.
44 changes: 24 additions & 20 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
# Developers guide
## I/ Documents your code using Doxygen
## I/ Documenting your code using Doxygen
### 1) How
#### General case
Our project use **Doxygen** to automatically generate the developer documentation. If you implement a new function in **Mmg**, please, comment it and give at least its interface description (function's arguments and return values).
Our project use **Doxygen** to automatically generate the developer documentation. If you implement a new function in **Mmg**, please, comment it and give at least its interface description (function arguments and return values).

For example a minimal documentation for the function that save the mesh may be this one:
```c
For example a minimal documentation for the function that saves the mesh may be this one:
<!-- do not mark this as C code or Doxygen will remove the interesting part -->
```
/**
* \param mesh pointer toward the mesh structure.
* \param filename pointer toward the name of file.
* \param mesh pointer to the mesh structure.
* \param filename pointer to the name of the file.
* \return 0 if failed, 1 otherwise.
*
* Save mesh data.
Expand All @@ -18,18 +19,19 @@ For example a minimal documentation for the function that save the mesh may be t
*/
int MMG3D_saveMesh(MMG5_pMesh mesh, char *filename);
```
Additionaly, it is a good practice to include text inside the routine to explain the work carried out.
Additionaly, it is good practice to include text inside the routine to explain the work carried out.

You can refer to the [Doxygen documentation](http://www.stack.nl/~dimitri/doxygen/) for a description of the **Doxygen** commands.

#### API's functions
Because the library header for Fortran users is automatically generated from the C header, you must add to your documentation the interface of the fortran function. Each line of this interface must begin with the `>` symbol and end with the `\n` one.
#### API functions
Because the library header for Fortran users is automatically generated from the C header, you must add the interface of the fortran function to your documentation. Each line of this interface must begin with the `>` symbol and end with `\n` (a backslash and the letter n).

For example, if the previous function is an API function, its documentation becames the following:
```c
For example, if the previous function is an API function, its documentation becomes the following:
<!-- do not mark this as C code or Doxygen will remove the interesting part -->
```
/**
* \param mesh pointer toward the mesh structure.
* \param filename pointer toward the name of file.
* \param mesh pointer to the mesh structure.
* \param filename pointer to the name of file.
* \return 0 if failed, 1 otherwise.
*
* Save mesh data.
Expand All @@ -47,17 +49,17 @@ For example, if the previous function is an API function, its documentation beca
*
*/
int MMG3D_saveMesh(MMG5_pMesh mesh, char *filename);
```
```

### 2) Where
Please, comments only your functions in the `.c` file, except for the **API**'s functions that must be documentated in the suitable `libmmg<X>.h` file (and only here).
Please, comments only your functions in the `.c` file, except for the **API** functions; these must be documentated in the appropriate `libmmg<X>.h` file (and only there).

## II/ Memory management: dynamic allocations and deallocations
We need to control the memory consumption in our applications so the memory used by dynamic allocations is counted and updated at each allocation and deallocation.
We need to control the memory consumption in our applications so the memory used by dynamic allocations is counted and updated at each allocation and deallocation.

Note that with a high verbosity (at least 6), you can check that at the end of the process the memory count is 0.

To make the update of memory consumption easier, we have wrapped the `malloc`, `calloc`, `realloc` and `free` functions into macros that must be called in place of the matching function.
To make the update of memory consumption easier, we have wrapped the `malloc`, `calloc`, `realloc` and `free` functions into macros that must be called in place of these functions.

| `C function` | `Mmg macro` |
|----------------------|-----------------------------------|
Expand All @@ -66,7 +68,7 @@ To make the update of memory consumption easier, we have wrapped the `malloc`, `
| `ptr = (type *) realloc(ptr,size*sizeof(type));`<br>`if ( high_verbosity )`<br>&nbsp;&nbsp;&nbsp;&nbsp;`printf(" ## Warning:%s:%d: %s reallocation.\n",__FILE__,__LINE__,tab_info);`| `MMG5_SAFE_REALLOC(ptr,prevSize,newSize,type,tab_name,law);` |
| `Decrease_memory_count(size); `<br>`free(ptr); ptr = NULL; `| `MMG5_DEL_MEM(mesh,ptr)`|

Note that other macros which aims to help to manage the memory have been implemented.
Note that other macros which aim to help to manage the memory have been implemented.

### 1) Allocations
To check that we have enough memory to allocate a pointer of size `siz` and to increment the memory counter, you must precede your allocation by a call to the `MMG5_ADD_MEM(mesh, siz, "tab_name", law)` macro.
Expand All @@ -87,6 +89,8 @@ MMG5_ADD_MEM(mesh,5*sizeof(double),"my array",exit(EXIT_FAILURE));
MMG5_SAFE_MALLOC(ptr,5,double,exit(EXIT_FAILURE));
```

That said, calling `exit` from a library function is not polite. You may wish to do something else in the `law` argument, for example setting a flag that tells your function to free any memory it allocated and return a value indicating failure.

### 2) Deallocations
To decrement the memory counter, to deallocate your pointer and to leave it pointing toward `NULL`, you just need to call the `MMG5_DEL_MEM(mesh,ptr)` macro.

Expand All @@ -111,5 +115,5 @@ Please, use the following configuration in your editor:
Besides, try to respect the following rules:
* declaration of variables in the top of the function;
* do not use exit(), use a return value instead;
* do not implement void API function;
* the main library functions returns `MMG<X>_SUCCESS` if success, `MMG<X>_LOWFAILURE` if fails but we can save the mesh, `MMG<X>_STRONGFAILURE` if fails and we can't save a conform mesh;
* do not implement void API functions;
* the main library functions returns `MMG<X>_SUCCESS` if successful, `MMG<X>_LOWFAILURE` if the function fails but we can save the mesh, and `MMG<X>_STRONGFAILURE` if fails and we can't save a conforming mesh.
83 changes: 42 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@
---

Mmg provides 3 applications and 4 libraries:
* the **mmg2d** application and library: mesh generation from a set of edges, adaptation and optimization of a bidimensionnal triangulation and isovalue discretization;
* the **mmg2d** application and library: mesh generation from a set of edges, adaptation and optimization of a bidimensional triangulation, and isovalue discretization;
* the **mmgs** application and library: adaptation and optimization of a surface triangulation and isovalue discretization;
* the **mmg3d** application and library: adaptation and optimization of a tetrahedral mesh, isovalue discretization and lagrangian movement;
* the **mmg** library gathering the **mmg2d**, **mmgs** and **mmg3d** libraries.
Expand All @@ -71,9 +71,9 @@ Mmg provides 3 applications and 4 libraries:
### Needed tools
To get and build Mmg, you will need:
* **Git**: to download the code you will have to use a git manager. You can install a git manager from the link below but there are many other git clients that you can use:
* [Official Git client](https://git-scm.com/download) (command line program)
* [Official Git client](https://git-scm.com/download) (command-line program)
* [GitKraken](https://www.gitkraken.com/)
* [SourceTree](https://www.sourcetreeapp.com/)
* [SourceTree](https://www.sourcetreeapp.com/)

Note that if you uses Microsoft Visual Studio (Windows OS), you can simply activate the Git Module of the application.

Expand All @@ -85,12 +85,12 @@ To get and build Mmg, you will need:
```
Add CMake to the system PATH for all users
```
</span>
</span>

### Mmg download and compilation
#### Unix-like OS (Linux, MacOS...)

1. Get the repository:
1. Get the repository:
```
wget https://github.com/MmgTools/mmg/archive/master.zip
```
Expand All @@ -103,24 +103,24 @@ To get and build Mmg, you will need:
* **src/mmg2d/** for files related to the mmg2d application;
* **src/mmgs/** for files related to the mmgs application;
* **src/mmg3d/** for files related to the mmg3d application;
* **src/common/** for files related to the both.
* **src/common/** for files related to all three.

2. Fast compilation (build both **mmg2d**, **mmgs**, **mmg3d**, the mmg2d static library (**libmmg3d.a**), the mmgs static library (**libmmgs.a**), the mmg3d static library (**libmmg3d.a**) and the mmg static library (**libmmg.a**)):
2. Fast compilation (build **mmg2d**, **mmgs**, **mmg3d**, the mmg2d static library (**libmmg3d.a**), the mmgs static library (**libmmgs.a**), the mmg3d static library (**libmmg3d.a**) and the mmg static library (**libmmg.a**)) all at once:
```
cd mmg
mkdir build
cd build
cmake ..
make
cd mmg
mkdir build
cd build
cmake ..
make
make install
```

If the `make install` command fail, try to run the `sudo make install` command.
If you don't have root access, please refers to the [Installation section](https://github.com/MmgTools/Mmg/wiki/Setup-guide#iii-installation) of the [setup guide](https://github.com/MmgTools/Mmg/wiki/Setup-guide#setup-guide).
If the `make install` command fails, try to run the `sudo make install` command.
If you don't have root access, please refer to the [Installation section](https://github.com/MmgTools/Mmg/wiki/Setup-guide#iii-installation) of the [setup guide](https://github.com/MmgTools/Mmg/wiki/Setup-guide#setup-guide).

The **mmg2d**, **mmgs** and **mmg3d** applications are available under the `mmg2d_O3`, `mmgs_O3` and `mmg3d_O3` commands.
The **mmg2d**, **mmgs** and **mmg3d** applications are available under the `mmg2d_O3`, `mmgs_O3` and `mmg3d_O3` commands.

Note that if you use some specific options and want to set it easily, you can use a shell script to execute the previous commands. An example is provided [here](https://github.com/MmgTools/mmg/wiki/Configure-script-for-CMake-(UNIX-like-OS)).
Note that if you use some specific options and want to set them easily, you can use a shell script to execute the previous commands. An example is provided [here](https://github.com/MmgTools/mmg/wiki/Configure-script-for-CMake-(UNIX-like-OS)).

#### Windows OS
The following compilation can be performed in any modern version of *Windows*
Expand All @@ -144,20 +144,19 @@ Universal windows platform development
cmake -G "Visual Studio 15 2017 Win64" ^
configure
```
Note that you can use a script to make this step easier (an example of script is provided [here](https://github.com/MmgTools/mmg/wiki/Configure-script-for-CMake-(Windows-OS))).

Note that you can use a script to make this step easier (an example of script is provided [here](https://github.com/MmgTools/mmg/wiki/Configure-script-for-CMake-(Windows-OS))).

Once the configuration script has finished without errors a `mmg.sln` file will be generated in the cmake_build directory.

6. Double click this file and the visual studio project will open. Then choose the project configuration (Release, Debug...).
Please, make sure that the project is set to Win32 or x64 and change it if is not.
6. Double click this file and the visual studio project will open. Then choose the project configuration (Release, Debug...) and make sure that the project is set to Win32 or x64.
Finally, in order to compile Mmg, right click the `INSTALL` project and select the option `BUILD`.

##### Compile with MinGW

1. Get a **C Compiler**:
1. Get a **C Compiler**:
* **MinGW** can be downloaded [here](http://mingw.org/). We recommand to install the *mingw-developer-tools*, *mingw32-base*, *mingw32-gcc-fortran*, *mingw32-gcc-g++* and *msys-base* packages;
* Edit the environment variables and add MinGW in your **PATH** variable. It can be done in the **advanced system settings** panel. (note that you must modify the **PATH** variable, not the **Path** one);
* Edit the environment variables and add MinGW in your **PATH** variable. It can be done in the **advanced system settings** panel. (note that you must modify the **PATH** variable, not **Path**);
* **MinGW** binaries are probably in `C:\MinGW\bin`
* the MinGW terminal is in `C:\MinGW\msys\1.0\msys`

Expand All @@ -169,42 +168,44 @@ Universal windows platform development
mingw32-make
```

Again, if you use some specific options and want to make the CMake configuration step easier, you can use a batch script. An example of script is provided [here](https://github.com/MmgTools/mmg/wiki/Configure-script-for-CMake-(Windows-OS)).
Again, if you use some specific options and want to make the CMake configuration step easier, you can use a batch script. An example script is provided [here](https://github.com/MmgTools/mmg/wiki/Configure-script-for-CMake-(Windows-OS)).

## Documentation
### Project's web page
Project's actualities and software tutorials can be found on the [mmgtools](http://www.mmgtools.org) web page.
### Project web page
Actualities of the project and software tutorials can be found on the [mmgtools](http://www.mmgtools.org) web page.

### Mmg's forum
### Forum
Share your comments and issues with other members of the Mmg community on the [Mmg forum](https://forum.mmgtools.org/).

### GitHub's Wiki
More detailed informations about the compilation and configuration of the mmg's applications are available on the project [wiki](https://github.com/MmgTools/mmg/wiki).
### GitHub Wiki
More detailed information about the compilation and configuration of Mmg applications is available on the project [wiki](https://github.com/MmgTools/mmg/wiki).

### Man-pages
### Man pages
Man pages are available inside the **doc/man** directory:
* To see the **mmg2d** man page, just tap `man ./doc/man/mmg2d.1.gz`
* To see the **mmgs** man page, just tap `man ./doc/man/mmgs.1.gz`
* To see the **mmg3d** man page, just tap `man ./doc/man/mmg3d.1.gz`
* To see the **mmg2d** man page, just run `man ./doc/man/mmg2d.1.gz`
* To see the **mmgs** man page, run `man ./doc/man/mmgs.1.gz`
* To see the **mmg3d** man page, run `man ./doc/man/mmg3d.1.gz`

### Code documentation
Run the `make doc` command to build the Doxygen documentation.
* To see the **mmg2d** documentation, open up the **mmg/doc/mmg2d/html/index.html** file;
* To see the **mmgs** documentation, open up the **mmg/doc/mmgs/html/index.html** file;
* To see the **mmg3d** documentation, open up the **mmg/doc/mmg3d/html/index.html** file.
Run the `make doc` command to build the Doxygen documentation, after running `cmake`
with the option `-DBUILD_DOC=yes` if you did not already do so.
You may wish to adapt `build/Doxyfile` to your liking.
* To see the **mmg2d** documentation, open the file **mmg/doc/mmg2d/html/index.html**,
* to see the **mmgs** documentation, open **mmg/doc/mmgs/html/index.html**, and
* ro see the **mmg3d** documentation, open **mmg/doc/mmg3d/html/index.html**.

## Platforms
The **mmg** applications are validated on OS X and on most of the Linux platforms.
The **mmg** applications are tested on OS X and on most of the Linux platforms.

## Contributing
Your contributions to the **mmg** project are welcomed. You can help us to improve
Your contributions to the **mmg** project are welcome. You can help us to improve
our code by many means:
* pull requests: please follow the [wiki's guideline](https://github.com/MmgTools/Mmg/wiki/Developers-wiki#pull-requests);
* pull requests: please follow the [guidelines on the wiki](https://github.com/MmgTools/Mmg/wiki/Developers-wiki#pull-requests);
* feature requests: please use the [Mmg forum](https://forum.mmgtools.org/);
* bug reports: please use the [GitHub issue tracker](https://github.com/MmgTools/mmg/issues/new);

## About the team
mmg's current developers and maintainers are Charles Dapogny, Cécile Dobrzynski, Pascal Frey and Algiane Froehly.
Mmg's current developers and maintainers are Charles Dapogny, Cécile Dobrzynski, Pascal Frey and Algiane Froehly.

Contact: [email protected]

Expand Down
4 changes: 2 additions & 2 deletions doc/doxygen/Doxyfile.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1033,7 +1033,7 @@ HTML_FOOTER =
# see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.

HTML_EXTRA_STYLESHEET =
HTML_EXTRA_STYLESHEET = @CMAKE_CURRENT_SOURCE_DIR@/doc/doxygen/custom.css

# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
Expand Down Expand Up @@ -1374,7 +1374,7 @@ FORMULA_TRANSPARENT = YES
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.

USE_MATHJAX = NO
USE_MATHJAX = YES

# When MathJax is enabled you can set the default output format to be used for
# the MathJax output. See the MathJax site (see:
Expand Down
14 changes: 14 additions & 0 deletions doc/doxygen/custom.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
/* -*- mode:css; css-indent-offset:2 -*-
* Style customizations for the Doxygen documentation of Mmgtools
* initial version by Mark Potse 03/2024
*/


div.contents {

}

p {
max-width: 800px; /* limit text line width, for readability */
}

6 changes: 3 additions & 3 deletions libexamples/mmg3d/IsosurfDiscretization_lsAndMetric/main.F90
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,12 +72,12 @@ PROGRAM main
! args of InitMesh:
! MMG5_ARG_start: we start to give the args of a variadic func
! MMG5_ARG_ppMesh: next arg will be a pointer over a MMG5_pMesh
! mmgMesh: your MMG5_pMesh (that store your mesh)
! mmgMesh: your MMG5_pMesh (that stores your mesh)
! MMG5_ARG_ppLs: next arg will be a pointer over a MMG5_pSol storing a level-set
! mmgLs: pointer toward your MMG5_pSol (that store your level-set)
! mmgLs: pointer to your MMG5_pSol (that stores your level-set)
! MMG5_ARG_ppMet: next arg will be a pointer over a MMG5_pSol that will
! store the input metric
! mmgMet: pointer toward your MMG5_pSol (that will store the input metric)
! mmgMet: pointer to your MMG5_pSol (that will store the input metric)
mmgMesh = 0
mmgLs = 0
mmgMet = 0
Expand Down
Loading

0 comments on commit 5788cf5

Please sign in to comment.