.. _ch02-fortran-example:

=============================================================
Fortran Example -- Newton's method to find a root
=============================================================

As a warm-up, study `the method <https://en.wikipedia.org/wiki/Newton%27s_method>`_.

``RootFinder.F90``: A driver routine.

.. literalinclude:: ./codes/newton_rootfinder/RootFinder.F90
   :language: fortran
   :linenos:

1. Exercise: Add a couple of lines in ``RootFinder.F90`` to show on
   the screen what the target function and the initial
   search value are.


``setup_module.F90``: A setup routine to initialize several runtime
parameters which are read in from the parameter file, ``rootFinder.init``.  

.. literalinclude:: ./codes/newton_rootfinder/setup_module.F90
   :language: fortran
   :linenos:

2. Exercise: Modify ``setup_module.F90`` to show the runtime
   parameters on the screen.

   
``read_initFile_module.F90``: A file that reads in user defined values
in a user provided parameter file, which is ``rootFinder.init`` in
this example.

.. literalinclude:: ./codes/newton_rootfinder/read_initFile_module.F90
   :language: fortran
   :linenos:

.. note::
   Check `article <https://www.nsc.liu.se/~boein/f77to90/a5.html>`_  to
   see what ``index`` and ``len_trim`` functions are.
   To see how they work, you can try::
       print*,index("I am a boy","boy")
       print*,len_trim("boy ")

      
``rootFinder.init``: A runtime parameter file, including a set of
runtime parameter values that are read in by ``read_initFile_module.F90``.

.. literalinclude:: ./codes/newton_rootfinder/rootFinder.init
   :language: fortran
   :linenos:



      
3. Exercise: In the Newton's root finding algorithm, it is important
   to choose a reasonable initial search value. Use a simple plotting
   tool (e.g., GNU plot) to verify your initial value is closer to the
   root of the target function.

4. Exercise: Do you need to recompile your code everytime you change
   your input runtime parameters in ``rootFinder.init``?

``findRootMethod_module.F90``: A module that holds two different
methods of root finder. Two methods are *Newton's* and *modified Newton's* methods.

.. literalinclude:: ./codes/newton_rootfinder/findRootMethod_module.F90
   :language: fortran
   :linenos:

``ftn_module.F90``: A module which includes two numerical evaluations.
They are the function evaluation and the derivative of function
evaluation. These subroutines are used in both *Newton's* and *modified Newton's* methods.

.. literalinclude:: ./codes/newton_rootfinder/ftn_module.F90
   :language: fortran
   :linenos:

5. Exercise: Add a couple of more functions of your choice and test them.

``output_module.F90``: A routine to write the results to a file.

.. literalinclude:: ./codes/newton_rootfinder/output_module.F90
   :language: fortran
   :linenos:



``definition.h``: A C-style header file which includes some definitions of code parameters.

.. literalinclude:: ./codes/newton_rootfinder/definition.h
   :language: C
   :linenos:

6. Exercise: Do you need to recompile your code everytime you change
   the values in ``defninition.h``? Without recompiling your code, do
   you see your code works properly?

7. Exercise: Try to delete ``newton`` and ``modified_newton`` from
   ``definition.h`` and see how it works. Do you see any different
   code behavior?

``makefile``: A makefile for compilation.

.. literalinclude:: ./codes/newton_rootfinder/makefile
   :language: make
   :linenos:

8. Exercise: What do you expect if you type ``make debug``?