begin_html [use: jsMath] [use: doc/doc.css]
<!--   For a more readable version of this file, execute
                  unix>  make .htmls
       in this directory and then point your browser to README.html 
     --------------------------------------------------------------  -->

<h2>
CLAWPACK Code to accompany this paper:
</h2>

{{{
R.J. LeVeque, <i>A Well-Balanced Path-Integral f-wave Method for 
Hyperbolic Problems with Source Terms</i>, 
[www.clawpack.org/links/wbfwave10 link to paper]
Submitted to a Special Issue of the Journal of Scientific Computing 
for the proceedings of a workshop on Numerical approximations of hyperbolic 
systems with source terms and applications, Castro-Urdiales, Spain, 2009
[http://www.math.sciences.univ-nantes.fr/NumHyp2009/  NumHyp2009]
}}}



Advection equation with a source term, $q_t + uq_x= -q\sigma_x(x)$.

Test 4 different methods for handling the source term, depending on the
parameter mthsrc defined in [code:setrun.py].

<ul>
<li> mthsrc = 1:  Fractional step method,
<li> mthsrc = 2:  f-wave splitting with source based on average of $Q$ on
either side of discontinuity (times jump in $\sigma$).
<li> mthsrc = 3:  Approach suggested in paper, averaging over two paths.
<li> mthsrc = 4:  Approach suggested in paper, using path corresponding to
true Riemann solution.
</ul>

See instructions at the bottom of this page for how to run the code and
make figures.


<h4>
Plots of results
</h4>
After running this code and creating plots via "make .plots", you should be
able to view the plots in [link: _plots/_PlotIndex.html].

If you want to change parameters and run all 4 methods automatically to
compare results, you can use [code: run_tests.py].  After running that code
via "python run_tests.py", you should be able to view all the plots at these
links:

<ul>
<li> mthsrc = 1:   [link: _plots.mthsrc1/_PlotIndex.html]
<li> mthsrc = 2:   [link: _plots.mthsrc2/_PlotIndex.html]
<li> mthsrc = 3:   [link: _plots.mthsrc3/_PlotIndex.html]
<li> mthsrc = 4:   [link: _plots.mthsrc4/_PlotIndex.html]
</ul>

<h4>
Fortran files
</h4>


<dl>
<dt>[code: Makefile]
<dd> Determines which version of fortran files
are used when compiling the code with make and specifies where output and
plots should be directed.  Type "make .help" at the Unix prompt for options.


<dt>[code: setprob.f]
<dd>
A routine by this name is called by the library routine 
[clawcode: clawpack/1d/lib/claw1ez.f]
and is generally used to set any values needed for the specific problem
being solved. 


<dt>[code: rp1.f]
<dd>
This is the Riemann solver, which takes the $q$ values stored in the
arrays <tt>ql</tt> and <tt>qr</tt> and returns the waves in the array
<tt>wave</tt> and speeds in the array <tt>s</tt> that result in solving the
Riemann problem at each cell interface, and the fluctuations <tt>amdq</tt>
and <tt>apdq</tt>.  See [claw:doc/rp1.html] for more information about 1d
Riemann solvers.


<dt>[code: fcns.f]
<dd>
Othe functions needed for the initial conditions and equilibrium solution.
The functions are also needed in the plotting routines, you should do
"make .f2py" to convert to a Python  module.


<dt>[code: qinit.f]
<dd>
This subroutine sets the initial data $q(x,0)$ at time $t=0$.

<dt>[code: src1.f]
<dd>
Applies source term if mthsrc==1 (set in [code:setprob.f]).  
Otherwise source terms are incorporated
into the Riemann solver.

</dl>

<h4>
Python files
</h4>
<dl>

<dt>[code: setrun.py]
<dd> This file contains a function that 
specifies what run-time parameters will be used.

<dt>[code: setplot.py]
<dd> This file contains a function that 
specifies what plots will be done and
sets various plotting parameters. 

<dt>[code: run_tests.py]
<dd> Run tests for all four approaches.

<dt>[code: make_figs_for_paper.py]
<dd> Run tests and make figures used in paper.

<dt>[code: setrun_for_paper.py]
<dd> Used by [code: make_figs_for_paper.py] to set parameters as in paper.

<dt>[code: setplot_for_paper.py]
<dd> Used by [code: make_figs_for_paper.py] to set parameters as in paper.

</dl>


<h4>
Data files
</h4>

These files are generated automatically by "make .setdata" from the data in
[code: setrun.py].

<dl>
<dt>[code: claw.data]
<dd> Clawpack runtime parameters.
The values in this file are read by the library routine
[clawcode: clawpack/1d/lib/claw1ez.f].  
Each line contains one or more values to be read
in, followed by comments that are ignored by the Fortran code but
may be used by Pythons scripts.



<dt> [code: setprob.data]
<dd> This file is read in by [code: setprob.f].


</dl>


<h4>Library routines</h4>


In addition to the Fortran routines in this library, several library
routines from [claw:clawpack/1d/lib] are used.  See the [code: Makefile]
to determine which ones are used.

<h4>Instructions</h4>

First do:
{{{
    $ f2py -c fcns.f -m fcns
}}}
to create some Python modules needed for plotting to make sure functions
are consistent with what is specified in [code: fcns.f].  Note that this
requires f2py.

To run one particular test case, modify [code:setrun.py] as desired and
then:

{{{
    $ make .plots
}}}

To run all four methods on the same example:

{{{
    $ python run_tests.py
}}}

To run all examples and create figures used in the paper:

{{{
    $ python make_figs_for_paper.py
    $ pdflatex show_figs_for_paper   # to view resulting plots
}}}

This uses [code: make_figs_for_paper.py].  

The figures that appear in the paper were produced by 
[code: make_figs_for_paper.py] using svn revision 345 of Clawpack 4.0
available via:

{{{
svn checkout http://kingkong.amath.washington.edu/svn/claw4/trunk@344 claw4
}}}

See [www.clawpack.org/doc] for installation instructions and documentation
on running and plotting options.

end_html