Skip to content

Github plan

Jump to bottom Edit New page
rjleveque edited this page Apr 17, 2011 · 16 revisions

Plan for moving Clawpack to GitHub

See Home for more wiki pages.

Reasons for moving

  • Loads on kingkong have increased dramatically and we want to move hosting elsewhere.
  • Subversion is not adequate for our needs any more -- too difficult to merge for example.
  • Most open source projects are moving to distributed version control, and GitHub seems best.
  • We want to make it easier for sub-projects to be managed independently.
  • Major changes and reorganization are planned for Clawpack 5.0 and this is the best time to make the switch.

More about Git and GitHub

Git appears to have a steeper learning curve than Mercurial, for example, but is also more powerful for large projects. Many other open source projects have recently moved to GitHub, including several Clawpack uses:

Fernando Perez's blog http://fperez.org/py4science/git.html has many useful links to get started.

Planned structure

There is now a GitHub account named clawpack: https://github.com/clawpack/

This account will host several repositories corresponding to different sub-projects.

Typically a user would have to clone several of these repositories to get everything needed to run a code (but many users would download a tarfile instead, which can be constructed from multiple repositories easily enough).

Splitting into multiple repositories has several advantages:

  • The repositories can be managed by different people who take control of those projects.
  • Developers would fork a new branch of the project they are working on and when satisfied send pull requests to the manager of that project.
  • Developers could also be given push permission to a project without having permission to other projects.
  • Users and developers not interested in GeoClaw, say, would not have to worry about what's going on in that repository.
  • Ultimately other large projects might be added, such as !ChomboClaw, and separating into repositories will keep other projects from growing huge.
  • Official releases of Clawpack will be done by creating tar files that combine together useful projects, e.g. there might be a tarfile for the full set of repositories, a GeoClaw tarfile useful for those doing geophysical flows, etc.

Initial sub-project repositories

The proposed initial repositories are:

  • classic: single-grid fortran codes

  • amrclaw: AMR codes

  • geoclaw: GeoClaw codes

  • pyclaw: Pure Python version and Python tools

  • sharpclaw: High-order methods (or will this be in pyclaw?)

  • petclaw: Massively parallel version using PetSC

  • riemann: Riemann solvers that can be used with any of the above. This could include Fortran and Python Riemann solvers, as well as vectorized and pointwise solvers. For the vectorized solvers, we are moving to interleaved arrays, but we should probably have a "non-interleaved" directory to keep Riemann solvers that have not yet been updated to the new format. The directory structure could be:

    • /riemann
      • riemann/pointwise
      • riemann/vectorized
        • riemann/vectorized/interleaved
        • riemann/vectorized/non-interleaved

Within each directory, there could be both Fortran and Python solvers, distinguished by long, explicit names.

ketch: We could indicate the equations, the solver type, the spatial dimension, and the transverse/normal attribute, in that order; e.g. burgers_exact_1D.f or euler_roe_with_efix_2D_t.f.

rjleveque: I'd suggest sticking naming conventions closer to what's currently used, e.g. rp1_burgers_exact.f and rpt2_euler_roe-with-efix.f for the above examples.

Alternatively, we could use more directory structure to indicate some of these attributes, but then it might be harder to find things.

  • visclaw: visualization tools (what's currently in python/pyclaw/plotters plus matlab tools, others?)

  • doc: Master top-level documentation. Sphinx rst files can point to rst files in doc directory of other repositories. The wiki for the doc repository can also serve as the top-level wiki for Clawpack (e.g. this page).

Question: Where do we put things that are now in clawpack/util such as Makefile.common and other utility scripts, some of which are now in clawpack/python?

Structure of each repository

We will maintain a uniform structure within each of these repositories. In particular, each should have the following set of subdirectories:

  • src: source code

  • doc: documentation, using Sphinx. Links among the documentation for different packages can be made using the intersphinx extension.

  • apps: applications -- examples of how this project can be used. Note that, e.g. classic/apps/acoustics/2d might contain same examples as amrclaw/apps/acoustics/2d (rather than the current system of a app directory having an amr subdirectory). This seems a better way to split it up though and there shouldn't be too much replication of code since, for example, the Riemann solvers will be in the riemann repository, needed by both.

  • tests: regression tests. These will be separate from the apps in the future since the needs are different.

Add a custom footer
Add a custom sidebar
Clone this wiki locally