From e2ca891f3567f11dfedb553381d07a04dabfefae Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 5 Jan 2016 18:58:12 +0000 Subject: [PATCH] Updated docs on tools. --- docs/source/helper.rst | 20 ---------------- docs/source/index.rst | 2 +- docs/source/plotting.rst | 51 ++++++++++++++++++++++++++++++++++------ docs/source/utils.rst | 33 ++++++++++++++++++++++++++ 4 files changed, 78 insertions(+), 28 deletions(-) delete mode 100644 docs/source/helper.rst create mode 100644 docs/source/utils.rst diff --git a/docs/source/helper.rst b/docs/source/helper.rst deleted file mode 100644 index 6abec1d2..00000000 --- a/docs/source/helper.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _helper: - -**************** -Helper utilities -**************** - -This section provides information on how to use the Python modules (in the ``tools`` package) that help manage gprMax files. - -inputfile_old2new.py --------------------- - -INSERT DESCRIPTION OF USAGE - - -outputfiles_merge.py --------------------- - -gprMax produces a separate output file for each trace (A-scan) in a B-scan. Combine the separate output files into one file using the Python module ``outputfiles_merge.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.outputfiles_merge basefilename modelruns``, where ``basefilename`` is the base name file of the output file series, e.g. for ``myoutput1.out``, ``myoutput2.out`` the base file name would be ``myoutput``, and ``modelruns`` is the number of output files to combine. - -UPDATE DESCRIPTION OF USAGE diff --git a/docs/source/index.rst b/docs/source/index.rst index 4bfed446..b8f5f180 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,7 +24,7 @@ gprMax User Guide :caption: Tools plotting - helper + utils .. toctree:: :maxdepth: 2 diff --git a/docs/source/plotting.rst b/docs/source/plotting.rst index 1f5f542d..7a375f87 100644 --- a/docs/source/plotting.rst +++ b/docs/source/plotting.rst @@ -11,9 +11,24 @@ A-scans plot_Ascan.py ------------- -Plot A-scans using the Python module ``plot_Ascan.py``. The module uses matplotlib to plot the time history for the electric and magnetic field components for any receivers in a model (each receiver gets a separate figure window). Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Ascan my_outputfile.out``. +This module uses matplotlib to plot the time history for the electric and magnetic field components for any receivers in a model (each receiver gets a separate figure window). Usage (from the top-level gprMax directory) is: -UPDATE DESCRIPTION OF USAGE +.. code-block:: none + + python -m gprMax python -m tools.plot_Ascan outputfile + +where ``outputfile`` is the name of output file including the path. + +There are optional command line arguments: + +* ``--fields`` to specify a subset of the default field components (``Ex``, ``Ey``, ``Ez``, ``Hx``, ``Hy`` or ``Hz``) as a list to plot +* ``-fft`` to plot the Fast Fourier Transform (FFT) of a single field component + +For example to plot the ``Ez`` field component with it's FFT: + +.. code-block:: none + + python -m gprMax python -m tools.plot_Ascan my_outputfile.out --fields Ez -fft B-scans ======= @@ -21,9 +36,16 @@ B-scans plot_Bscan.py ------------- -gprMax produces a separate output file for each trace (A-scan) in the B-scan. Plot an image of the B-scan using the Python module ``plot_Bscan.py``. Usage (from the top-level gprMax directory) is: ``python -m tools.plot_Bscan my_outputfile.out --field fieldcomponent``, where ``fieldcomponent`` is the name of field to plot, e.g. ``Ex``, ``Ey``, ``Ez``, ``Hx``, ``Hy`` or ``Hz``. +gprMax produces a separate output file for each trace (A-scan) in the B-scan. These must be combined into a single file using the ``outputfiles_merge.py`` module (described in the :ref:`other utilities section `). This module uses matplotlib to plot an image of the B-scan. Usage (from the top-level gprMax directory) is: -UPDATE DESCRIPTION OF USAGE +.. code-block:: none + + python -m tools.plot_Bscan outputfile --field fieldcomponent + +where: + +* ``outputfile`` is the name of output file including the path +* ``--field`` is the name of field to plot, e.g. ``Ex``, ``Ey``, ``Ez``, ``Hx``, ``Hy`` or ``Hz`` .. _waveforms: @@ -31,15 +53,30 @@ UPDATE DESCRIPTION OF USAGE Built-in waveforms ================== -This section provides definitions of the functions that are used to create the built-in waveforms. +This section describes the definitions of the functions that are used to create the built-in waveforms, and how to plot them. plot_builtin_wave.py -------------------- -INSERT DESCRIPTION OF USAGE +This module uses matplotlib to plot one of the built-in waveforms and it's FFT. Usage (from the top-level gprMax directory) is: +.. code-block:: none -Example plots are shown using the parameters: amplitude of one, frequency of 1GHz, time window of 6ns, and a time step of 1.926ps. + python -m tools.plot_builtin_wave type amp freq timewindow dt + +where: + +* ``type`` is the type of waveform, e.g. gaussian, ricker etc... +* ``amp`` is the amplitude of the waveform +* ``freq`` is the centre frequency of the waveform +* ``timewindow`` is the time window to view the waveform, i.e. the time window of the proposed simulation +* ``dt`` is the time step to view waveform, i.e. the time step of the proposed simulation + +There is an optional command line argument: + +* ``-fft`` to plot the FFT of the waveform + +Example plots of all the built-in waveforms are shown using the parameters: amplitude of one, frequency of 1GHz, time window of 6ns, and a time step of 1.926ps. gaussian ^^^^^^^^ diff --git a/docs/source/utils.rst b/docs/source/utils.rst new file mode 100644 index 00000000..9bcdb605 --- /dev/null +++ b/docs/source/utils.rst @@ -0,0 +1,33 @@ +.. _utils: + +*************** +Other utilities +*************** + +This section provides information on how to use the other Python modules in the ``tools`` package to help manage gprMax files. + +inputfile_old2new.py +-------------------- + +This modules assists with the process of migrating input files from the syntax of the old (pre v.3) version of gprMax to the new syntax. It will produce a new input file with the old syntax (attempted to be!) translated to the new syntax. Usage (from the top-level gprMax directory) is: + +.. code-block:: none + + python -m tools.inputfile_new2old inputfile + +where ``inputfile`` is the name of input file including the path. + + +outputfiles_merge.py +-------------------- + +gprMax produces a separate output file for each trace (A-scan) in a B-scan. This module combines the separate output files into a single file, and offers to remove the separate output files afterwards. Usage (from the top-level gprMax directory) is: + +.. code-block:: none + + python -m tools.outputfiles_merge basefilename modelruns + +where: + +* ``basefilename`` is the base name file of the output file series, e.g. for ``myoutput1.out``, ``myoutput2.out`` the base file name would be ``myoutput`` +* ``modelruns`` is the number of output files to combine \ No newline at end of file