From 188731062f71c9f0673c1107b0f826978c9e5926 Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 29 Mar 2016 16:13:25 +0100 Subject: [PATCH 1/6] Restructuring some of the docs. --- docs/source/geometry_snapshots.rst | 66 ---------------- docs/source/images/antenna_like_GSSI_1500.png | Bin 0 -> 22697 bytes docs/source/index.rst | 3 +- docs/source/input.rst | 6 +- docs/source/output.rst | 72 ++++++++++++++++-- docs/source/user_libraries.rst | 34 +++++++++ 6 files changed, 105 insertions(+), 76 deletions(-) delete mode 100644 docs/source/geometry_snapshots.rst create mode 100644 docs/source/images/antenna_like_GSSI_1500.png create mode 100644 docs/source/user_libraries.rst diff --git a/docs/source/geometry_snapshots.rst b/docs/source/geometry_snapshots.rst deleted file mode 100644 index e0aa4d5e..00000000 --- a/docs/source/geometry_snapshots.rst +++ /dev/null @@ -1,66 +0,0 @@ -*************************** -Geometry and Snapshot files -*************************** - -The geometry and snapshot files use the open source Visualization ToolKit (VTK) (http://www.vtk.org) format which can be viewed in many free readers, such as Paraview (http://www.paraview.org). Paraview is an open-source, multi-platform data analysis and visualization application. It is available for Linux, Mac OS X, and Windows. - -Geometry files -============== - -The ``#geometry_view:`` command produces either ImageData (.vti) for a per-cell geometry view, or PolygonalData (.vtp) for a per-cell-edge geometry view. The per-cell geometry views also show the location of the PML regions and any sources and receivers in the model. The following are steps to get started with viewing geometry files in Paraview: - -.. _pv_toolbar: - -.. figure:: images/paraview_toolbar.png - - Paraview toolbar showing ``gprMax_info`` macro button. - -#. **Open the file** either from the File menu or toolbar. -#. Click the **Apply** button in the Properties panel. You should see an outline of the volume of the geometry view. -#. Install the ``gprMax_info.py`` Python script, that comes with the gprMax source code (in the ``tools/Paraview macros`` directory), as a macro in Paraview. This script makes it quick and easy to view the different materials in a geometry file. To add the script as a macro in Paraview choose the file from the Macros->Add new macro menu. It will then appear as a shortcut button in the toolbar as shown in :numref:`pv_toolbar`. You only need to do this once, the macro will be kept in Paraview for future use. -#. Click the ``gprMax_info`` shortcut button. All the materials in the model should appear in the Pipeline Browser as Threshold items as shown in :numref:`pv_pipeline`. - -.. _pv_pipeline: - -.. figure:: images/paraview_pipeline.png - :width: 350 px - - Paraview Pipeline Browser showing list of materials in an example model. - -.. tip:: - * You can turn on and off the visibility of materials using the eye icon in the Pipeline Browser. You can select multiple materials using the Shift key, and by shift-clicking the eye icon, turn the visibility of multiple materials on and off. - - * You can set the Color and Opacity of materials from the Properties panel. - - -Snapshot files -============== - -The ``#snapshot:`` command produces an ImageData (.vti) snapshot file for each time instance requested. - -.. tip:: - You can take advantage of Python scripting to easily create a series of snapshots. For example, to create 30 snapshots starting at time 0.1ns until 3ns in intervals of 0.1ns, use the following code snippet in your input file. Replace ``xs, ys, zs, xf, yf, zf, dx, dy, dz`` accordingly. - - .. code-block:: none - - #python: - from gprMax.input_cmd_funcs import * - for i in range(1, 31): - snapshot(xs, ys, zs, xf, yf, zf, dx, dy, dz, (i/10)*1e-9, 'snapshot' + str(i)) - #end_python: - -The following are steps to get started with viewing snapshot files in Paraview: - -#. **Open the file** either from the File menu or toolbar. Paraview should recognise the time series based on the file name and load in all the files. -#. Click the **Apply** button in the Properties panel. You should see an outline of the snapshot volume. -#. Use the **Coloring** drop down menu to select either **E-field** or **H-field**, and the further drop down menu to select either **Magnitude**, **x**, **y** or **z** component. -#. From the **Representation** drop down menu select **Surface**. -#. You can step through or play as an animation the time steps using the **time controls** in the toolbar. - -.. tip:: - - * Turn on the Animation View (View->Animation View menu) to control the speed and start/stop points of the animation. - - * Use the Color Map Editor to adjust the Color Scaling. - - diff --git a/docs/source/images/antenna_like_GSSI_1500.png b/docs/source/images/antenna_like_GSSI_1500.png new file mode 100644 index 0000000000000000000000000000000000000000..92bcf1ad2d9eef61b8a5144ab86f28b1efb575ef GIT binary patch literal 22697 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

;gwAsprNLou zI7HgKa{dr4D)sPq@m$aPv=MhV-nz7^I};~(L<-NQjL2ME*+rM}(q-duu0*;+T4524 zXp(7$isd~fQRq+vg(W;R_r&f%v&dd2a4Y8e7y2DoKDW&M3DBPSl!vQ zolJ}!ao|CcZfTi$H?(wkG0+ECc-coNLsh@S3V!EGpjE>`cvPu3s?czddk!wo^ij!t zTdW}u0|ckFk^@%WINVe`. File structure -============== +-------------- The output file has the following HDF5 attributes at the root (``/``): @@ -97,9 +99,67 @@ Within each individual ``tl`` group are the following datasets: * ``Itotal`` is an array containing the time history (for the model time window) of the values of the total (field) current in the transmission line. -Viewing output -============== +Snapshots +--------- + +Snapshot files use the open source Visualization ToolKit (VTK) (http://www.vtk.org) format which can be viewed in many free readers, such as Paraview (http://www.paraview.org). Paraview is an open-source, multi-platform data analysis and visualization application. It is available for Linux, Mac OS X, and Windows. The ``#snapshot:`` command produces an ImageData (.vti) snapshot file containing electric and magnetic field data and current data for each time instance requested. + +.. tip:: + You can take advantage of Python scripting to easily create a series of snapshots. For example, to create 30 snapshots starting at time 0.1ns until 3ns in intervals of 0.1ns, use the following code snippet in your input file. Replace ``xs, ys, zs, xf, yf, zf, dx, dy, dz`` accordingly. + + .. code-block:: none + + #python: + from gprMax.input_cmd_funcs import * + for i in range(1, 31): + snapshot(xs, ys, zs, xf, yf, zf, dx, dy, dz, (i/10)*1e-9, 'snapshot' + str(i)) + #end_python: + +The following are steps to get started with viewing snapshot files in Paraview: + +#. **Open the file** either from the File menu or toolbar. Paraview should recognise the time series based on the file name and load in all the files. +#. Click the **Apply** button in the Properties panel. You should see an outline of the snapshot volume. +#. Use the **Coloring** drop down menu to select either **E-field** or **H-field**, and the further drop down menu to select either **Magnitude**, **x**, **y** or **z** component. +#. From the **Representation** drop down menu select **Surface**. +#. You can step through or play as an animation the time steps using the **time controls** in the toolbar. + +.. tip:: + + * Turn on the Animation View (View->Animation View menu) to control the speed and start/stop points of the animation. + + * Use the Color Map Editor to adjust the Color Scaling. + + +Geometry output +=============== + +Geometry files use the open source Visualization ToolKit (VTK) (http://www.vtk.org) format which can be viewed in many free readers, such as Paraview (http://www.paraview.org). Paraview is an open-source, multi-platform data analysis and visualization application. It is available for Linux, Mac OS X, and Windows. + +The ``#geometry_view:`` command produces either ImageData (.vti) for a per-cell geometry view, or PolygonalData (.vtp) for a per-cell-edge geometry view. The per-cell geometry views also show the location of the PML regions and any sources and receivers in the model. The following are steps to get started with viewing geometry files in Paraview: + +.. _pv_toolbar: + +.. figure:: images/paraview_toolbar.png + + Paraview toolbar showing ``gprMax_info`` macro button. + +#. **Open the file** either from the File menu or toolbar. +#. Click the **Apply** button in the Properties panel. You should see an outline of the volume of the geometry view. +#. Install the ``gprMax_info.py`` Python script, that comes with the gprMax source code (in the ``tools/Paraview macros`` directory), as a macro in Paraview. This script makes it quick and easy to view the different materials in a geometry file. To add the script as a macro in Paraview choose the file from the Macros->Add new macro menu. It will then appear as a shortcut button in the toolbar as shown in :numref:`pv_toolbar`. You only need to do this once, the macro will be kept in Paraview for future use. +#. Click the ``gprMax_info`` shortcut button. All the materials in the model should appear in the Pipeline Browser as Threshold items as shown in :numref:`pv_pipeline`. + +.. _pv_pipeline: + +.. figure:: images/paraview_pipeline.png + :width: 350 px + + Paraview Pipeline Browser showing list of materials in an example model. + +.. tip:: + * You can turn on and off the visibility of materials using the eye icon in the Pipeline Browser. You can select multiple materials using the Shift key, and by shift-clicking the eye icon, turn the visibility of multiple materials on and off. + + * You can set the Color and Opacity of materials from the Properties panel. + -There are a number of free tools available to read HDF5 files. Also MATLAB has high- and low-level functions for reading and writing HDF5 files, i.e. ``h5info`` and ``h5disp`` are useful for returning information and displaying the contents of HDF5 files respectively. gprMax includes some Python modules (in the ``tools`` package) to help you view output data. These are documented in the :ref:`tools section `. diff --git a/docs/source/user_libraries.rst b/docs/source/user_libraries.rst new file mode 100644 index 00000000..2765863b --- /dev/null +++ b/docs/source/user_libraries.rst @@ -0,0 +1,34 @@ +.. _user-libs: + +************* +User libaries +************* + +The user libraries sub-package is where useful modules contributed by users are stored. + +antennas.py +=========== + +This library currently features models of antennas similar to: + +* a Geophysical Survey Systems, Inc. (GSSI) 1.5 GHz (Model 5100) antenna (http://www.geophysical.com) +* a MALA Geoscience 1.2 GHz antenna (http://www.malags.com/) + +These antenna models can be accessed from within a block of Python code in your simulation. For example, to use Python to include an antenna model similar to a GSSI 1.5 GHz antenna at a location 0.125m, 0.094m, 0.100m (x,y,z) using a 1mm spatial resolution: + +.. code-block:: none + + #python: + from user_libs.antennas import antenna_like_GSSI_1500 + antenna_like_GSSI_1500(0.125, 0.094, 0.100, 0.001) + #end_python: + +.. figure:: images/antenna_like_MALA_1200.png + :width: 600 px + + FDTD geometry mesh showing an antenna model similar to a MALA 1.2GHz antenna (skid removed for illustrative purposes). + +.. figure:: images/antenna_like_GSSI_1500.png + :width: 600 px + + FDTD geometry mesh showing an antenna model similar to a GSSI 1.5GHz antenna (skid removed for illustrative purposes). From 3d912435234ff3fdd5c52e3eb9965fbdcdcd084d Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 29 Mar 2016 16:21:28 +0100 Subject: [PATCH 2/6] Further restructuring, --- docs/source/examples_advanced.rst | 6 +++--- docs/source/examples_simple_2D.rst | 6 +++--- docs/source/index.rst | 20 ++++++++++---------- docs/source/openmp_mpi.rst | 6 +++--- docs/source/user_libraries.rst | 10 +++++----- 5 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/source/examples_advanced.rst b/docs/source/examples_advanced.rst index af7b49d5..3fedf4d0 100644 --- a/docs/source/examples_advanced.rst +++ b/docs/source/examples_advanced.rst @@ -1,6 +1,6 @@ -****************** -Advanced modelling -****************** +***************** +Advanced features +***************** This section provides example models of some of the more advanced features of gprMax. Each example comes with an input file which you can download and run. diff --git a/docs/source/examples_simple_2D.rst b/docs/source/examples_simple_2D.rst index 0f7b3a2e..f0e1b009 100644 --- a/docs/source/examples_simple_2D.rst +++ b/docs/source/examples_simple_2D.rst @@ -1,6 +1,6 @@ -**************************** -Introductory/basic 2D models -**************************** +************************ +Introductory models (2D) +************************ This section provides some introductory example models in 2D that demonstrate basic features of gprMax. Each example comes with an input file which you can download and run. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6fa163c1..412307e7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,22 +21,14 @@ gprMax User Guide .. toctree:: :maxdepth: 2 - :caption: Additional Python tools + :caption: Python tools plotting utils .. toctree:: :maxdepth: 2 - :caption: Advanced topics - - python_scripting - user_libraries - openmp_mpi - -.. toctree:: - :maxdepth: 2 - :caption: Examples + :caption: Example models examples_simple_2D examples_antennas @@ -49,6 +41,14 @@ gprMax User Guide faqs screencasts +.. toctree:: + :maxdepth: 2 + :caption: Advanced topics + + python_scripting + openmp_mpi + user_libraries + .. toctree:: :maxdepth: 2 :caption: Appendices diff --git a/docs/source/openmp_mpi.rst b/docs/source/openmp_mpi.rst index 81cbaf13..7935f928 100644 --- a/docs/source/openmp_mpi.rst +++ b/docs/source/openmp_mpi.rst @@ -1,8 +1,8 @@ .. _openmp-mpi: -************************ -Parallelism - OpenMP/MPI -************************ +*********** +Parallelism +*********** OpenMP ====== diff --git a/docs/source/user_libraries.rst b/docs/source/user_libraries.rst index 2765863b..af5a8f45 100644 --- a/docs/source/user_libraries.rst +++ b/docs/source/user_libraries.rst @@ -23,12 +23,12 @@ These antenna models can be accessed from within a block of Python code in your antenna_like_GSSI_1500(0.125, 0.094, 0.100, 0.001) #end_python: +.. figure:: images/antenna_like_GSSI_1500.png + :width: 600 px + + FDTD geometry mesh showing an antenna model similar to a GSSI 1.5 GHz antenna (skid removed for illustrative purposes). + .. figure:: images/antenna_like_MALA_1200.png :width: 600 px FDTD geometry mesh showing an antenna model similar to a MALA 1.2GHz antenna (skid removed for illustrative purposes). - -.. figure:: images/antenna_like_GSSI_1500.png - :width: 600 px - - FDTD geometry mesh showing an antenna model similar to a GSSI 1.5GHz antenna (skid removed for illustrative purposes). From e8eb6f9d936b6913c027fe3b0bb461d1c2185042 Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 29 Mar 2016 16:27:21 +0100 Subject: [PATCH 3/6] Further restructuring. --- docs/source/examples_simple_2D.rst | 2 +- docs/source/index.rst | 24 ++++++++++++++---------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/source/examples_simple_2D.rst b/docs/source/examples_simple_2D.rst index f0e1b009..53513ba5 100644 --- a/docs/source/examples_simple_2D.rst +++ b/docs/source/examples_simple_2D.rst @@ -1,5 +1,5 @@ ************************ -Introductory models (2D) +Introductory models - 2D ************************ This section provides some introductory example models in 2D that demonstrate basic features of gprMax. Each example comes with an input file which you can download and run. diff --git a/docs/source/index.rst b/docs/source/index.rst index 412307e7..ff7573ba 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,7 +28,15 @@ gprMax User Guide .. toctree:: :maxdepth: 2 - :caption: Example models + :caption: Advanced topics + + python_scripting + openmp_mpi + user_libraries + +.. toctree:: + :maxdepth: 2 + :caption: Examples examples_simple_2D examples_antennas @@ -43,18 +51,14 @@ gprMax User Guide .. toctree:: :maxdepth: 2 - :caption: Advanced topics - - python_scripting - openmp_mpi - user_libraries - -.. toctree:: - :maxdepth: 2 - :caption: Appendices + :caption: Accuracy and performance comparisons_analytical comparisons_numerical benchmarking + +.. toctree:: + :maxdepth: 2 + references From 85aef4b0e7d34b242cb95d0ac886b40fae3d05f3 Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 29 Mar 2016 16:33:30 +0100 Subject: [PATCH 4/6] Edit to title. Correction of domain function example. --- docs/source/python_scripting.rst | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/docs/source/python_scripting.rst b/docs/source/python_scripting.rst index 8dc5bfd3..235fafbb 100644 --- a/docs/source/python_scripting.rst +++ b/docs/source/python_scripting.rst @@ -1,8 +1,8 @@ .. _python-scripting: -**************** -Python scripting -**************** +************************ +Scripting the input file +************************ The input file has now been made scriptable by permitting blocks of Python code to be specified between ``#python`` and ``#end_python`` commands. The code is executed when the input file is read by gprMax. You don't need any external tools, such as MATLAB, to generate larger, more complex input files for building intricate models. Python scripting means that gprMax now includes :ref:`libraries of more complex objects, such as antennas `, that can be easily inserted into a model. You can also access a number of built-in constants from your Python code. @@ -22,22 +22,6 @@ You can access the following built-in variables from your Python code: * ``number_model_runs`` is the total number of runs specified when the model was initially executed, i.e. from ``python -m gprMax my_input_file -n number_of_model_runs`` * ``inputdirectory`` is the path to the directory where your input file is located. -Antenna models -============== - -You can also access a user library of antenna models. This library currently features models of antennas similar to: - -* a Geophysical Survey Systems, Inc. (GSSI) 1.5 GHz (Model 5100) antenna (http://www.geophysical.com) -* a MALA Geoscience 1.2 GHz antenna (http://www.malags.com/) - -These antenna models can be accessed from within a block of Python code in your simulation. For example, to use Python to include an antenna model similar to a GSSI 1.5 GHz antenna at a location 0.125m, 0.094m, 0.100m (x,y,z) using a 1mm spatial resolution: - -.. code-block:: none - - #python: - from user_libs.antennas import antenna_like_GSSI_1500 - antenna_like_GSSI_1500(0.125, 0.094, 0.100, 0.001) - #end_python: Functions for input commands ============================ @@ -48,7 +32,7 @@ To make it easier to create commands within a block of Python code, there is a b #python: from gprMax.input_cmd_funcs import * - domain = domain(0.2 0.2 0.2) + domain = domain(0.2, 0.2, 0.2) for x in range(0, 8) cylinder(0.02 + x * 0.02, 0.05, 0, 0.020 + x * 0.02, 0.05, domain[2], 0.005, 'pec’) #end_python: From 8e8295c3b2108951c9a7dae1333ad7a29372983c Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 29 Mar 2016 16:36:04 +0100 Subject: [PATCH 5/6] Changed some headings. --- docs/source/examples_simple_2D.rst | 2 +- docs/source/index.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/examples_simple_2D.rst b/docs/source/examples_simple_2D.rst index 53513ba5..501f299a 100644 --- a/docs/source/examples_simple_2D.rst +++ b/docs/source/examples_simple_2D.rst @@ -1,5 +1,5 @@ ************************ -Introductory models - 2D +Introductory (2D) models ************************ This section provides some introductory example models in 2D that demonstrate basic features of gprMax. Each example comes with an input file which you can download and run. diff --git a/docs/source/index.rst b/docs/source/index.rst index ff7573ba..231e34fa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -59,6 +59,7 @@ gprMax User Guide .. toctree:: :maxdepth: 2 + :caption: Appendices references From 7799113e47b75934246f36dc8cd2a815000f897b Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Tue, 29 Mar 2016 16:39:29 +0100 Subject: [PATCH 6/6] Fixed a couple of typos. --- docs/source/benchmarking.rst | 6 +++--- docs/source/comparisons_analytical.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/benchmarking.rst b/docs/source/benchmarking.rst index a89d543c..7df66a68 100644 --- a/docs/source/benchmarking.rst +++ b/docs/source/benchmarking.rst @@ -1,8 +1,8 @@ .. _benchmarking: -************ -Benchmarking -************ +************************ +Performance benchmarking +************************ This section provides information and results from performance benchmarking of gprMax. diff --git a/docs/source/comparisons_analytical.rst b/docs/source/comparisons_analytical.rst index 5ecb36df..9b223bb1 100644 --- a/docs/source/comparisons_analytical.rst +++ b/docs/source/comparisons_analytical.rst @@ -15,7 +15,7 @@ This example is of a Hertzian dipole, i.e. an additive source (electric current :language: none :linenos: -The function ``hertzian_dipole_fs``, which can be found in the ``analytical solutions`` module in the ``tests`` sub-package, computes the analytical solution. +The function ``hertzian_dipole_fs``, which can be found in the ``analytical_solutions`` module in the ``tests`` sub-package, computes the analytical solution. Results -------