Subject: [Fenics] [[email-masked]: [Branch ~fenics-core/fenics-doc/main] Rev 11: Added Poisson.ufl and main.cpp file and create link for download.]

From: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 14:18:53 +0200

Any ideas on how to keep the code in the documentation and the actual
demos in sync? Should we have a script that copies all the source
files? Or should we do the opposite: extract the demos from the
documentation?

--
Anders

Subject: [Branch ~fenics-core/fenics-doc/main] Rev 11: Added Poisson.ufl and main.cpp file and create link for download.
From: [email-masked]
To: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 12:01:19 -0000

------------------------------------------------------------
revno: 11
committer: Kristian B. Ølgaard <[email-masked]>
branch nick: fenics-doc
timestamp: Tue 2010-04-27 13:57:42 +0200
message:
  Added Poisson.ufl and main.cpp file and create link for download.
added:
  source/demos/cpp/pde/Poisson.ufl
  source/demos/cpp/pde/poisson_main.cpp
modified:
  source/demos/cpp/pde/cpp_poisson.rst

--
lp:fenics-doc
https://code.launchpad.net/~fenics-core/fenics-doc/main

You are subscribed to branch lp:fenics-doc.
To unsubscribe from this branch go to https://code.launchpad.net/~fenics-core/fenics-doc/main/+edit-subscription
=== added file 'source/demos/cpp/pde/Poisson.ufl'
--- source/demos/cpp/pde/Poisson.ufl	1970-01-01 00:00:00 +0000
+++ source/demos/cpp/pde/Poisson.ufl	2010-04-27 11:57:42 +0000
@@ -0,0 +1,20 @@
+# Copyright (C) 2005-2009 Anders Logg.
+# Licensed under the GNU LGPL Version 2.1.
+#
+# First added:  2005
+# Last changed: 2009-09-08
+#
+# The bilinear form a(v, u) and linear form L(v) for
+# Poisson's equation.
+#
+# Compile this form with FFC: ffc -l dolfin Poisson.ufl.
+
+element = FiniteElement("Lagrange", triangle, 1)
+
+v = TestFunction(element)
+u = TrialFunction(element)
+f = Coefficient(element)
+g = Coefficient(element)
+
+a = inner(grad(v), grad(u))*dx
+L = v*f*dx + v*g*ds

=== modified file 'source/demos/cpp/pde/cpp_poisson.rst'
--- source/demos/cpp/pde/cpp_poisson.rst	2010-04-27 11:12:29 +0000
+++ source/demos/cpp/pde/cpp_poisson.rst	2010-04-27 11:57:42 +0000
@@ -10,7 +10,7 @@
 
 This text is C++ specific
 
-Some UFL code in ``Poisson.h``
+Some UFL code in :download:`Poisson.ufl`.
 
 .. code-block:: python
 
@@ -71,3 +71,6 @@
     }
   };
 
+All this should be in the same :download:`main.cpp<poisson_main.cpp>` file.
+
+

=== added file 'source/demos/cpp/pde/poisson_main.cpp'
--- source/demos/cpp/pde/poisson_main.cpp	1970-01-01 00:00:00 +0000
+++ source/demos/cpp/pde/poisson_main.cpp	2010-04-27 11:57:42 +0000
@@ -0,0 +1,87 @@
+// Copyright (C) 2006-2009 Anders Logg.
+// Licensed under the GNU LGPL Version 2.1.
+//
+// First added:  2006-02-07
+// Last changed: 2010-04-05
+//
+// This demo program solves Poisson's equation
+//
+//     - div grad u(x, y) = f(x, y)
+//
+// on the unit square with source f given by
+//
+//     f(x, y) = 10*exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02)
+//
+// and boundary conditions given by
+//
+//     u(x, y) = 0        for x = 0 or x = 1
+// du/dn(x, y) = -sin(5*x) for y = 0 or y = 1
+
+#include <dolfin.h>
+#include "Poisson.h"
+
+using namespace dolfin;
+
+// Source term (right-hand side)
+class Source : public Expression
+{
+  void eval(Array<double>& values, const Array<double>& x) const
+  {
+    double dx = x[0] - 0.5;
+    double dy = x[1] - 0.5;
+    values[0] = 10*exp(-(dx*dx + dy*dy) / 0.02);
+  }
+};
+
+// Boundary flux (Neumann boundary condition)
+class Flux : public Expression
+{
+  void eval(Array<double>& values, const Array<double>& x) const
+  {
+    values[0] = -sin(5*x[0]);
+  }
+};
+
+// Sub domain for Dirichlet boundary condition
+class DirichletBoundary : public SubDomain
+{
+  bool inside(const Array<double>& x, bool on_boundary) const
+  {
+    return x[0] < DOLFIN_EPS or x[0] > 1.0 - DOLFIN_EPS;
+  }
+};
+
+int main()
+{
+  // Create mesh and function space
+  UnitSquare mesh(32, 32);
+  Poisson::FunctionSpace V(mesh);
+
+  // Define boundary condition
+  Constant u0(0.0);
+  DirichletBoundary boundary;
+  DirichletBC bc(V, u0, boundary);
+
+  // Define variational problem
+  Poisson::BilinearForm a(V, V);
+  Poisson::LinearForm L(V);
+  Source f;
+  Flux g;
+  L.f = f;
+  L.g = g;
+
+  // Compute solution
+  VariationalProblem problem(a, L, bc);
+  problem.parameters["linear_solver"] = "iterative";
+  Function u(V);
+  problem.solve(u);
+
+  // Save solution in VTK format
+  File file("poisson.pvd");
+  file << u;
+
+  // Plot solution
+  plot(u);
+
+  return 0;
+}

---

From: Kristian Oelgaard <[email-masked]>
Date: Tue, 27 Apr 2010 14:52:37 +0200 (CET)

> files? Or should we do the opposite: extract the demos from the

Good question, initially I thought copying from DOLFIN to documentation was the way to go, but on second thought the other  way around might be better.
The reason is that if the demos break, then they will be fixed in the documentation which makes is more likely that the accompanying text (and code snippets) will also be corrected.

Kristian

> --
> Anders
>
>
> ---------- Forwarded message ----------
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkvW1i0ACgkQTuwUCDsYZdGwLgCdFPgbJke73i5QHWPo50NaQXxU
> 6cEAniYG20A/l8GYI389W10WZng8P7Vb
> =ik1b
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>
>

---

From: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 15:01:34 +0200

> The reason is that if the demos break, then they will be fixed in the documentation which makes is more likely that the accompanying text (and code snippets) will also be corrected.

Yes, that might be the best option, to have a script that generates
the tree of demos from the documentation. The problem of course is
that there will be a higher threshold for developing demos but maybe
that is a good thing (if it means better demos and documentation).

--
Anders

---

From: "Garth N. Wells" <[email-masked]>
Date: Tue, 27 Apr 2010 14:34:56 +0100

On 27/04/10 14:01, Anders Logg wrote:
>> On 27 April 2010 14:18, Anders Logg<[email-masked]>  wrote:
> the tree of demos from the documentation.

Sounds a bit tricky with the revision control system as we have it now 
with the demos as part of the DOLFIN code repository.

What we could do is move all the demos to the fenics-doc repository and 
remove them from dolfin-dev. We could then follow the model that PETSc 
uses for its build system and have scons download fenics-doc into the 
fenics-dev tree upon build. For DOLFIN releases, we can copy fenics-doc 
into the tarball.

Garth

> The problem of course is

---

From: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 15:38:09 +0200

On Tue, Apr 27, 2010 at 02:34:56PM +0100, Garth N. Wells wrote:
> Sounds a bit tricky with the revision control system as we have it
> now with the demos as part of the DOLFIN code repository.
>
> What we could do is move all the demos to the fenics-doc repository
> and remove them from dolfin-dev. We could then follow the model that
> PETSc uses for its build system and have scons download fenics-doc
> into the fenics-dev tree upon build. For DOLFIN releases, we can
> copy fenics-doc into the tarball.

Sounds good to me. And the downloading into the tarball could be added
to the pre-release hook in the release script.

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Tue, 27 Apr 2010 15:51:21 +0200 (CET)

On 27 April 2010 15:34, Garth N. Wells <[email-masked]> wrote:
>>> Good question, initially I thought copying from DOLFIN to documentation
>>> was the way to go, but on second thought the other  way around might be
>>> better.
>>> The reason is that if the demos break, then they will be fixed in the
>>> documentation which makes is more likely that the accompanying text (and
>>> code snippets) will also be corrected.
>>>
>>> Kristian
>>
> Sounds a bit tricky with the revision control system as we have it now with
> the demos as part of the DOLFIN code repository.
>
> remove them from dolfin-dev. We could then follow the model that PETSc uses
> for its build system and have scons download fenics-doc into the fenics-dev
> tree upon build. For DOLFIN releases, we can copy fenics-doc into the
> tarball.

fenics-dev or dolfin-dev? I agree that this approach sounds like the best option.

Kristian

---

From: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 16:11:08 +0200

> fenics-dev or dolfin-dev? I agree that this approach sounds like the best option.

There is no dolfin-dev repository (I guess Garth means
dolfin-main). There is a fenics-dev repository (mainly containing the
common release script) but I don't think it is suitable for DOLFIN
demos.

Here's another crazy idea. How about throwing all the core packages
(DOLFIN, FFC, UFL, UFC, FIAT) into the same tree? The main advantages
would be removal of version incompatibility (and a more streamlined
user experience). The main disadvantage (the reason for having
separate projects in the first place) is it makes it difficult for the
developers of the different projects to make their own decisions and
develop in their own pace, but that might be less of a problem these
days when the same group of people are more or less maintaining all
packages.

--
Anders

---

From: Andy Ray Terrel <[email-masked]>
Date: Tue, 27 Apr 2010 09:27:52 -0500

A couple of thoughts.

The separation of the projects is highly desirable.  I know plenty of
people who just pick and choose what they download and use.

My suggestion would be to create a test script that extracts the demo
code and runs them.  It should be pretty simple to get a code that
extracts from the demos, but then how would you make sure the text is
correct?  If the test fails then there is a bit more incentive to go
back and edit the text as well.

-- Andy

---

From: "Garth N. Wells" <[email-masked]>
Date: Tue, 27 Apr 2010 15:30:05 +0100

On 27/04/10 15:11, Anders Logg wrote:
>> On 27 April 2010 15:34, Garth N. Wells<[email-masked]>  wrote:
>>>
>>>

I see some merit in this, but think that we're better off with the 
separation.

Garth

---

From: "Garth N. Wells" <[email-masked]>
Date: Wed, 28 Apr 2010 10:59:08 +0100

> code snippets) will also be corrected.

We'll usually have the source code for a demo broken into pieces in the 
documentation with an explanation for each part of the code (rather than 
one big chunk), so how would this work with syncing to the actual demo code?

Garth

---

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 28 Apr 2010 12:05:19 +0200 (CET)

On 28 April 2010 11:59, Garth N. Wells <[email-masked]> wrote:
> documentation with an explanation for each part of the code (rather than one
> big chunk), so how would this work with syncing to the actual demo code?

I think the entire main.cpp file (and UFL ) should be available for download as it is now.
Then, if a demo breaks one will have to manually modify the code snippets and the text.
(and of course the code in main.cpp and the UFL file if appropriate)

Kristian

---

From: Anders Logg <[email-masked]>
Date: Wed, 28 Apr 2010 18:26:38 +0200

> (and of course the code in main.cpp and the UFL file if appropriate)

Shouldn't it be possible to write a script that extracts the pieces
and patches them together?

That way, the buildbot will test nightly that the documentation makes
sense.

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 28 Apr 2010 18:38:44 +0200 (CET)

> and patches them together?

Probably, assuming that all pieces match up to the entire code.
For each demo, the piece of code you decide to present in the documentation might be different, so the script will have to be custom made for each demo.
I think we should stick to adding two or three demos in the beginning to see how we can get this running in some automated way.

> That way, the buildbot will test nightly that the documentation makes

This should definitely happen in some form.
I guess we should also have stable releases of the documentation and follow the DOLFIN release cycle and version numbering.

Kristian

> iEYEARECAAYFAkvYYb4ACgkQTuwUCDsYZdF7SACfUNGoVdS376NtL/wCToQSqnCQ
> 0roAnA6ABN+tLPfhHB60FzT2gAsAGkVh
> =QraE

---

From: "Garth N. Wells" <[email-masked]>
Date: Thu, 29 Apr 2010 14:15:52 +0100

On 28/04/10 17:26, Anders Logg wrote:
>> On 28 April 2010 11:59, Garth N. Wells<[email-masked]>  wrote:
>>>
>>>

Possible, but someone needs to do it and figure out a syntax do indicate 
what line to extract.

Garth

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 15:43:09 +0200 (CET)

On 29 April 2010 15:15, Garth N. Wells <[email-masked]> wrote:
>>>> one

How about this:

All the code for a particular demo is in main.cpp as it is now, which we will use to test against DOLFIN and make available for download in the documentation.

The script should then look for all .. code-block:: directives in the documentation and check if the code is present in main.cpp. 

The code block presented in the documentation then has to be an exact copy of what is in main.cpp and we don't need to worry about the order or if all pieces of code match up to the entire main.cpp file.

Kristian

---

From: Anders Logg <[email-masked]>
Date: Thu, 29 Apr 2010 15:44:57 +0200

On Thu, Apr 29, 2010 at 03:43:09PM +0200, Kristian Oelgaard wrote:
> The script should then look for all .. code-block:: directives in
> the documentation and check if the code is present in main.cpp.
>

Should main.cpp be in DOLFIN or should it be part of the
documentation?

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 15:54:01 +0200 (CET)

> Should main.cpp be in DOLFIN or should it be part of the

It is easier if we make it part of the documentation since Sphinx will copy files that are available for download to the build/_downloads directory when building the documentation. Then it is also more naturally to test the demos against DOLFIN before building the documentation.

Kristian

> iEYEARECAAYFAkvZjVkACgkQTuwUCDsYZdGEMQCfUnpBkofTQ/8y2eTY8RebFjfe
> jhkAmwQ4IhulNmnNo+wDsDWKl3LVqMcT
> =Ko/x

---

From: "Garth N. Wells" <[email-masked]>
Date: Thu, 29 Apr 2010 14:55:14 +0100

On 29/04/10 14:54, Kristian Oelgaard wrote:
>>> >>>Then, if a demo breaks one will have to manually modify the code
>>> snippets
>>> >>>and the text.
>>> All the code for a particular demo is in main.cpp as it is now, which
>>> we will use to test against DOLFIN and make available for download in
>>> the documentation.
>>>
>>> The code block presented in the documentation then has to be an exact
>>> copy of what is in main.cpp and we don't need to worry about the
>>> order or if all pieces of code match up to the entire main.cpp file.
>>
> It is easier if we make it part of the documentation since Sphinx will
> copy files that are available for download to the build/_downloads
> directory when building the documentation. Then it is also more
> naturally to test the demos against DOLFIN before building the
> documentation.
>

Agree.

Should we wait until we flesh out the documentation for Poisson (and 
maybe another demo) and then move the demos from dolfin-main to fenics-doc?

Garth

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 16:02:05 +0200 (CET)

On 29 April 2010 15:55, Garth N. Wells <[email-masked]> wrote:
> Should we wait until we flesh out the documentation for Poisson (and maybe
> another demo) and then move the demos from dolfin-main to fenics-doc?

Yes, let's stick to the two demos we have now (Cahn-Hilliard and Poisson) and get them running for both C++ and Python, set up the scripts to check code blocks, and test against DOLFIN. I think the two demos are different enough to expose most of the problems that we'll encounter.

Kristian

---

From: Anders Logg <[email-masked]>
Date: Thu, 29 Apr 2010 16:06:41 +0200

On Thu, Apr 29, 2010 at 04:02:05PM +0200, Kristian Oelgaard wrote:
> Yes, let's stick to the two demos we have now (Cahn-Hilliard and
> Poisson) and get them running for both C++ and Python, set up the
> scripts to check code blocks, and test against DOLFIN. I think the
> two demos are different enough to expose most of the problems that
> we'll encounter.

So we need two scripts?

One script to extract demos from the documentation and into DOLFIN (or
should we at all bundle the demos with DOLFIN, maybe not). Then only
the buildbot needs this script.

And another script (as part of the documentation) to sanity check the
code snippets against the code.

--
Anders

---

From: "Garth N. Wells" <[email-masked]>
Date: Thu, 29 Apr 2010 15:12:31 +0100

On 29/04/10 15:06, Anders Logg wrote:
>> On 29 April 2010 15:55, Garth N. Wells<[email-masked]>  wrote:
>>>
>>>
>>>> On 29 April 2010 15:44, Anders Logg<[email-masked]>  wrote:
>>>>>
>>>>>> On 29 April 2010 15:15, Garth N. Wells<[email-masked]>  wrote:
>>>>>>>
>>>>>>>

I wouldn't bundle the demos with DOLFIN. We'll have a 'dolfin-lib' and a 
'fenics-doc' package. What about demos from other FEniCS packages?

Garth

---

From: Anders Logg <[email-masked]>
Date: Thu, 29 Apr 2010 16:18:06 +0200

On Thu, Apr 29, 2010 at 03:12:31PM +0100, Garth N. Wells wrote:
> I wouldn't bundle the demos with DOLFIN. We'll have a 'dolfin-lib'
> and a 'fenics-doc' package.

Yes, that sounds good.

> What about demos from other FEniCS packages?

Don't know. The other relevant demos are the demos for UFL and FFC and
that in itself is a bit strange, to have two sets of .ufl files with a
pretty large overlap between them.

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 16:18:46 +0200 (CET)

> the buildbot needs this script.

This script should be on the buildbot I think, then the demos will be tested like they
are now and if they fail corrections have to be implemented in the documentation.
Then the other script will check if the corrections are also propagated to the text.
I don't have a strong opinion about whether or not to distribute the demos with DOLFIN.

> code snippets against the code.

This one we definitely need and it should be run when building the docs on the server.
(and preferably before any commits).

Kristian

> iEYEARECAAYFAkvZknEACgkQTuwUCDsYZdGEPQCgjioEBFvXGmMKP/miU1lDfc2J
> QKsAn07gR61iDuNYzyOuznjE4sY7MTyD
> =pVfV

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 16:22:36 +0200 (CET)

> pretty large overlap between them.

True, the most important purpose of these demos is for testing in my book.

Kristian

> iEYEARECAAYFAkvZlR4ACgkQTuwUCDsYZdEHAACgl3TuVo/eOHC9c2CfsyEuDTpV
> oiQAnj5ZFgg1UqW1pNRbCIS2p2S4ey3U
> =kLT3