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.

Downloading the code gallery

You can get the entire code gallery from its github home
by using the command

git clone https://github.com/dealii/code-gallery.git

This creates a directory 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:

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

where you replace 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

@f{align}
...
@f}

to explain ideas.

CMakeLists.txt:
A Cmake file that allows others to build your
code. It must be possible to simply run it via

cmake -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.

that specifies what requirements you need of the
underlying deal.II installation for your program
to run. The entries are Cmake variables that are
set during deal.II configuration and correspond to
the items you find printed in the summary at the
end of a cmake run when configuring
deal.II.

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.