The deal.II Code Gallery
The deal.II "code gallery" is an extension to the deal.II tutorial. While the tutorial's emphasis is on teaching aspects of deal.II by providing concrete examples — and extensive documentation and discussion — of how parts of deal.II are used in applications, the intent of the code gallery is to provide starting points for your own codes by making available codes others have already written.
As a general rule:
- The code gallery is not part of deal.II. The applications in the code gallery were written by users who wanted to make their codes available.
- The applications in the code gallery are generally not as well tested or documented as the tutorial programs. These codes come with no warranty at all. If you have questions, you need to contact the authors of these codes, not the authors of deal.II.
- We welcome additions and improvements to existing codes, as well as new code gallery applications! Most users start their own applications from an existing tutorial program. Having more starting points helps others, but it also gives code gallery authors additional ways to get recognition for their own codes! See below for instructions on how to contribute.
Quick links
What's in it?
To see what codes are part of the code gallery, see this list. You can also see how these codes build on the tutorial programs by finding the open circles on the graph of connections between tutorial and code gallery codes.
Downloading the code gallery
You can get the entire code gallery from its github home
by using the command
This creates a directory
git clone https://github.com/dealii/code-gallery.git
code-gallery/
that
contains all code gallery programs.
If you want to generate the deal.II documentation
locally and want it to also cross-link to the code
gallery, you need to do the step above within your copy
of deal.II, i.e., so that the command above creates a
directory code-gallery/
parallel to the
include/
,
source/
, and
examples/
directories (and others).
Contributing codes to the gallery
First: We appreciate all contributions! We have tried to set the bar to entry as low as possible. In essence, here is all you have to do:
- Create a fork of the git repository for the code gallery. To this end, you need to have an account at github.com. Log in, then go to https://github.com/dealii/code-gallery and click on the "Fork" symbol at the top right.
-
This yields a copy of the code gallery repository to
which you are allowed to write (a "fork"). At the
right side of the page, you will find its HTTPS
address. Check out a copy of it to your local hard drive via
git clone https://github.com/yourusername/code-gallery.git
myusername
with your github user name. -
Go into the
code-gallery
directory just generated. Within it, create a new directory for your project, named as you like. -
Put your source files and everything else you need
into this directory. In addition, the following files
and subdirectories need to exist:
-
Readme.md
: A markdown formatted file that provides a basic overview of what this program does. You can use latex-style formulas enclosed in$...$
, or offset via
to explain ideas.@f{align*}{ ... @f}
-
CMakeLists.txt
: A Cmake file that allows others to build your code. It must be possible to simply run it viacmake -DDEAL_II_DIR=/path/to/dealii . ; make ; make run
-
doc/entry-name
: A file that contains a simple, short name of the program. This will likely match the directory name, but can contain spaces and special characters (encoded in HTML, if necessary). This name will be used in the title line of the program's page, as well as in the the list of programs. -
doc/tooltip
: A one-line description of the program that is shown when hovering over a symbol in the connection graph. -
doc/builds-on
: A list of the formstep-XX step-YY gallery-NNNN gallery-MMMM
XX
andYY
are the numbers of existing tutorials programs that your application builds on, andNNNN
andMMMM
are the names of existing gallery applications. This information is used to build the connection graph for tutorial and code gallery applications. -
doc/author
: A list of authors and their email addresses in the formJane Doe <jane@doe.org>, Helga Mustermann <helga@email.de>
-
doc/dependencies
: A file with a list of entries of the formDEAL_II_WITH_CXX11 DEAL_II_WITH_TRILINOS
cmake
run when configuring deal.II.
-
-
Create a branch in your local git copy:
git branch my-code-gallery-project git checkout my-code-gallery-project
-
Add your code gallery project to the git directory and
upload it to your fork of the repository:
git add my-project-name git push origin my-code-gallery-project
-
Go to your github code-gallery page, which should be
named
https://github.com/myusername/code-gallery
. Sign in if necessary. It should allow you to create a "pull request" for your new code gallery project. Do so -- this will alert the deal.II maintainers to the fact that you want to contribute a new project, and sets up a short code review process.