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

   
See the list of programs that are part of the code gallery.
   
Downloading the programs of the code gallery is easy.
   
Contribute your own codes as a starting point for others.

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

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:

  1. 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.
  2. 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.
  3. Go into the code-gallery directory just generated. Within it, create a new directory for your project, named as you like.
  4. 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.

    • doc/builds-on: A list of the form

      step-XX step-YY gallery-NNNN gallery-MMMM
      where XX and YY are the numbers of existing tutorials programs that your application builds on, and NNNN and MMMM 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 form

      Jane Doe <jane@doe.org>,
      Helga Mustermann <helga@email.de>

    • doc/dependencies: A file with a list of entries of the form

      DEAL_II_WITH_CXX11 DEAL_II_WITH_TRILINOS
      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.

  5. Create a branch in your local git copy:
    git branch my-code-gallery-project
    git checkout my-code-gallery-project
  6. 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
  7. 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.