Subject: [Fenics] FEniCS Demo documentation

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 16 Jun 2010 18:31:42 +0200

Hello,

I've finished a first iteration on documenting the Poisson demo (from
dolfin/demo/pde/poisson).

Check it out and let me know what you think.

The Python version is here:

 http://www.fenics.org/newdoc/demos/python/pde/poisson/poisson.html

and the C++ version is here:

http://www.fenics.org/newdoc/demos/cpp/pde/poisson/poisson.html

Note that I need to finish the Programmer's reference part of the
documentation before I can insert links to the relevant classes used
in the demos.

http://www.fenics.org/newdoc/programmers-reference/index.html

Kristian

---

From: Anders Logg <[email-masked]>
Date: Wed, 16 Jun 2010 22:09:06 +0200

Looks good. I noticed a couple of things:

1. It would be good if class names were in another font (like courier
style), \texttt{VariationalProblem} etc

2. Would it be better with another variable name instead of h since
that will be used as mesh size in other demos. Why not g?

3. Is the normal flux + or - grad(u).n? I think of it as -grad(u).n.

4. Typo in "The implemented in a single Python file"

5. g is used in (f, g) instead of h (but maybe h should be changed to g)

The documentation seems to be coming along pretty well. It may be time
for you to ask people to contribute specific parts. For example,
Johannes and Harish could contribute with some documentation of how to
get Debian/Ubuntu packages and building with Dorsal. Others can
contribute with writing specific pages for the programmer's
reference, and Hans Petter can contribute with preparing his tutorial
in reST (and split it in Python and C++ versions).

--
Anders

On Wed, Jun 16, 2010 at 06:31:42PM +0200, Kristian Oelgaard wrote:
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 17 Jun 2010 11:29:28 +0200

> style), \texttt{VariationalProblem} etc

Once the Programmer's reference is up and running, I think we should
just use links to the class documentation (and member functions).

> that will be used as mesh size in other demos. Why not g?

I'll change h --> g for all Neumann BCs.

> 3. Is the normal flux + or - grad(u).n? I think of it as -grad(u).n.

The equation is:

- \Delta u = f

multiplying by v:

- v \Delta u = vf

integration by parts and switching to UFL:

inner( grad(v), grad(u))*dx  - v*inner(grad(u), n)*ds = v*f*dx

if we use g = - inner(grad(u), n) then

inner( grad(v), grad(u))*dx  + v*g*ds = v*f*dx

so

a = inner( grad(v), grad(u))*dx
L = v*f*dx - v*g*ds

then we need to use g = sin(5x) for the demo to give the same solution.

Of course we can move the '-' from L to g (which is what we have now)
but then the form does not follow directly from our equations.

> 4. Typo in "The implemented in a single Python file"

Fixed.

> 5. g is used in (f, g) instead of h (but maybe h should be changed to g)

yes.

> in reST (and split it in Python and C++ versions).

I need to figure out the framework for the Programmer's reference and
write the styleguide for contributing, but the Tutorial and
Installation parts can be written now.

Kristian

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.10 (GNU/Linux)
>
> iEYEARECAAYFAkwZL2IACgkQTuwUCDsYZdHZ5QCfa7fC+zyjjYtWG2HncJVdtl/4
> UskAn0LZx1DNof5lIRs9/+TzPhNbaErU
> =esYb
> -----END PGP SIGNATURE-----
>
>

---

From: Harish Narayanan <[email-masked]>
Date: Thu, 17 Jun 2010 13:20:58 +0200

> in reST (and split it in Python and C++ versions).

Attached is an initial version of the installation-with-Dorsal page.
More refinements to come.

Harish
# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: [email-masked]
# target_branch: bzr+ssh://bazaar.launchpad.net/~fenics-core/fenics-\
#   doc/main/
# testament_sha1: 43d59f44e12ab7935b3467cffc0786f6294f1c6f
# timestamp: 2010-06-17 13:19:15 +0200
# base_revision_id: [email-masked]\
#   3axpfdj6si3naqpt
# 
# Begin patch
=== modified file 'source/installation.rst'
--- source/installation.rst	2010-06-03 15:01:39 +0000
+++ source/installation.rst	2010-06-17 11:18:11 +0000
@@ -19,8 +19,43 @@
 Installation using Dorsal
 *************************
 
-Explain how to use the Dorsal script, and how it can be used to install
-individual packages.
+The easiest way to install FEniCS on a UNIX-like operating environment
+is to use Dorsal. Dorsal is a simple shell script that automates the
+process of fetching, compiling and installing the various FEniCS
+sub-projects and their requisite dependencies. It currently supports
+the following platforms:
+
+* Debian GNU/Linux 4.0, 5.0, unstable
+* Fedora 10, 11, 12          
+* Mac OS X 10.4, 10.5, 10.6
+* openSUSE 11.1, 11.2      
+* Red Hat Enterprise Linux 4, 5 
+* Ubuntu 8.10, 9.04, 9.10, 10.04 LTS
+* Gentoo (and Sabayon) Linux
+
+It is easy to extend support to other similar platforms. Please let us
+know if that you are interested, and we can work together toward
+adding this functionality.
+
+In order to install the FEniCS project on one of the supported
+platforms listed above, follow the following steps:
+
+#. Fetch the most recent version of Dorsal from its `download page <https://launchpad.net/dorsal/+download>`_.
+#. Uncompress the archive to a convenient location.
+#. Navigate to this folder and tweak dorsal.cfg to your liking.
+#. Invoke the build script by running:
+      ./dorsal.sh
+#. At this point, Dorsal attempts to guess your operating environment (platform) and provides a list of instructions to ensure your system is ready for installing FEniCS. Go through these carefully, and copy and paste appropriate commands into another terminal window to prepare your system.
+#. Once you've completed these steps, hit enter to begin the installation!
+
+
+If all goes according to plan, you should see a lot of
+compilation-related text scroll past your screen and eventually end up
+with a complete, up-to-date installation of various FEniCS projects
+and their corresponding dependencies.
+
+Don't forget to follow any post-build instructions before rushing off to try the demos!
+
 
 ***
 FFC

# Begin bundle
SKcKEgtPWgIA

---

From: Anders Logg <[email-masked]>
Date: Fri, 18 Jun 2010 10:09:58 +0200

> just use links to the class documentation (and member functions).

ok, sounds good.

> I'll change h --> g for all Neumann BCs.

ok.

> but then the form does not follow directly from our equations.

Perhaps g = grad u . n (with + sign) is better now when I think of
it. It looks better in two ways: we avoid the "-" sign in both the
definition of g and the definition of the form. So it should be

  g = sin(5x)
  L = v*f*dx + v*g*ds

Then one just needs to remember that g is the negative flux (if one
thinks of -grad u . n as the flux, but not everyone does).

--
Anders

---

From: Hans Petter Langtangen <[email-masked]>
Date: Fri, 18 Jun 2010 16:35:37 +0200

> 3. Is the normal flux + or - grad(u).n? I think of it as -grad(u).n.

For k*inner(grad(u), grad(v))*dx, -k*grad(u).n is the right flux. It has
a minus sign. Some people use the word flux for grad(u).n, but that's
sloppy - normal derivative is then better.

Hans Petter

---

From: Anders Logg <[email-masked]>
Date: Fri, 18 Jun 2010 16:47:37 +0200

> sloppy - normal derivative is then better.

I agree that -k*grad(u).n is the flux, but perhaps the question is
whether to include the term "flux" at all in the Poisson demo. If it
is included, then we should have a minus sign, both in the definition
of g = -k*grad(u).n and in the form where we get -<g, v>*ds. But if we
don't mention "flux" then it looks strange with two minus signs.

--
Anders

---

From: Hans Petter Langtangen <[email-masked]>
Date: Fri, 18 Jun 2010 17:36:30 +0200

> don't mention "flux" then it looks strange with two minus signs.

I agree - in the Poisson demo we skip "flux" and use "normal derivative"
instead and define it as grad(u).n.

Hans Petter

---

From: Kristian Oelgaard <[email-masked]>
Date: Fri, 18 Jun 2010 17:55:49 +0200

> instead and define it as grad(u).n.

OK, I'll change this in the text and code then.

Kristian

---

From: "Garth N. Wells" <[email-masked]>
Date: Fri, 18 Jun 2010 13:53:03 -0400

> instead and define it as grad(u).n.

I agree too.

Garth

---

From: Johannes Ring <[email-masked]>
Date: Wed, 23 Jun 2010 15:26:55 +0200

> in reST (and split it in Python and C++ versions).

Here is a patch (attached) for installation instructions on Debian and Ubuntu.

BTW, it seems like sections '=', subsections '-', and subsubsetions
'^' looks the same. Why is that?

Johannes

PS: I updated Sphinx to 0.6.7 on fenics.org.

# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: [email-masked]
# target_branch: bzr+ssh://bazaar.launchpad.net/~fenics-core/fenics-\
#   doc/main/
# testament_sha1: 8395c67a8ae31034e90fa90c7acd6d4b3e3c3720
# timestamp: 2010-06-23 15:16:14 +0200
# base_revision_id: [email-masked]\
#   e6gs3qlkbn811owa
# 
# Begin patch
=== modified file 'source/installation.rst'
--- source/installation.rst	2010-06-18 11:23:21 +0000
+++ source/installation.rst	2010-06-23 13:14:43 +0000
@@ -13,7 +13,55 @@
 Installation for Debian/Ubuntu users
 ************************************
 
-Explain how to install the packages.
+Debian
+======
+
+The latest stable FEniCS releases are available in Debian sid. To
+install, simply click `here <apt://fenics>`_ (requires ``aptlinex``) or
+run the following command as root::
+
+    aptitude install fenics
+
+Ubuntu
+======
+
+FEniCS is available in the official Ubuntu repositores as of Ubuntu
+10.04 (Lucid). Simply click `here <apt://fenics>`_ to install
+(requires ``apturl``) or install from the Ubuntu Software
+Center. FEniCS can also be installed by running the following
+command::
+
+    sudo apt-get install fenics
+
+The FEniCS PPA
+--------------
+
+The official Ubuntu repositories may not always contain the latest
+stable FEniCS releases. To stay current with the latest releases, add
+the `FEniCS Personal Package Archive
+<https://launchpad.net/~fenics/+archive/ppa>`_ (PPA) to your Ubuntu
+system. You can do this by going to **System > Administration >
+Software Sources > Third-Party Software** and click on **Add**. Then
+type in ``ppa:fenics/ppa`` and click on **Add Source** and then
+**Close**. A dialog box should appear, asking whether you'd like to
+update the list of repositories. Select **Reload** to update the
+list. You can then install FEniCS from the Software Center.
+
+Here is a list of commands for installing FEniCS from the FEniCS PPA
+for those preferring the command line:
+
+.. code-block:: sh
+
+    sudo add-apt-repository ppa:fenics/ppa
+    sudo apt-get update
+    sudo apt-get install fenics
+
+.. note::
+
+    The ``add-apt-repository`` command is not available on older (pre
+    9.10) Ubuntu systems. Please see the `FEniCS PPA page
+    <https://launchpad.net/~fenics/+archive/ppa>`_ for instructions on
+    these systems.

# Begin bundle

---

From: Harish Narayanan <[email-masked]>
Date: Wed, 23 Jun 2010 15:40:23 +0200

> '^' looks the same. Why is that?

Take a look at the generated HTML code. Perhaps these symbols result in
different classes all having the same CSS associated with them.

Harish

---

From: Johannes Ring <[email-masked]>
Date: Wed, 23 Jun 2010 15:54:33 +0200

> different classes all having the same CSS associated with them.

I have created the section

Ubuntu
======

and the subsection

The FEniCS PPA
--------------

and they look very similar. After looking at the generated HTML code I
see that they are not exactly the same:

<div class="section" id="ubuntu">
<h3>Ubuntu<a class="headerlink" href="#ubuntu" title="Permalink to
this headline">¶</a></h3>

and

<div class="section" id="the-fenics-ppa">
<h4>The FEniCS PPA<a class="headerlink" href="#the-fenics-ppa"
title="Permalink to this headline">¶</a></h4>

Both have class="section" and I tried to change it to subsection but
it didn't have any effect. It would be nice if sections and
subsections were looking more different.

Johannes

---

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 23 Jun 2010 16:06:50 +0200

> I have created the section

Since '==' and '--' both end up as class=section, I guess our only
option is to modify <h3> and <h4> in whatever css we use.
Let's worry about style later, it would be nice to use the same style as:

http://new.fenics.org/Main_Page

Kristian

---

From: Johannes Ring <[email-masked]>
Date: Wed, 23 Jun 2010 16:16:12 +0200

> http://new.fenics.org/Main_Page

OK, that's fine.

Johannes