publicImage/gprMax
1
0
派生 0
镜像自地址 https://gitee.com/sunhf/gprMax.git 已同步 2025-08-07 23:14:03 +08:00
代码 工单 软件包 项目 版本发布 百科 动态

Updated refs and removed unused hash commands

浏览代码
这个提交包含在：
Craig Warren
2023-03-30 11:38:37 +01:00
父节点 0afa629262
当前提交 8ccf1fe122
共有 7 个文件被更改，包括 104 次插入 和 181 次删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

86
docs/source/input_hash_cmds.rst
查看文件

@@ -10,7 +10,7 @@ Introduction
gprMax has a choice of two methods for building a model to simulate:
1. A **text-based (ASCII) input file**, which can be created with any text editor, and uses a series of gprMax commands which begin with the hash character (``#``). This method is recommended for beginners and those not familiar with Python, and is described in this section of the documentation.
2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features. The Python API is documented in the :ref:`input_api` section.
2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. This method is recommended for those who prefer to use Python or need access to specific API-only advanced features, and is documented in the :ref:`Python API <input_api>` section.
The general syntax of the hash commands is:
@@ -143,17 +143,6 @@ Allows you to include a title for your model. This title is saved in the output
where ``str1`` can contain white space characters to separate individual words. The title has to be contained in a single line.
#messages:
----------
Allows you to control the amount of information displayed on screen when gprMax is run. The syntax of the command is:
.. code-block:: none
#messages: c1
where ``c1`` can be either y (yes) or n (no) which turns on or off the messages on the screen. The default value is y. When messages are on, gprMax will display on the screen information the translation of space and time values to cell coordinates, iteration number, material parameters etc... This information can be useful for error checking.
#output_dir:
------------
@@ -166,16 +155,16 @@ Allows you to control the directory where output file(s) will be stored. The sy
where ``str1`` can be either the absolute path to the directory for the output file(s) or a path relative to the directory of the input files. The default value is the same as the directory of the input files.
#num_threads:
#cpu_threads:
-------------
Allows you to control how many OpenMP threads (usually the number of physical CPU cores available) are used when running the model. The most computationally intensive parts of gprMax, which are the FDTD solver loops, have been parallelised using `OpenMP <http://openmp.org>`_ which supports multi-platform shared memory multiprocessing. The syntax of the command is:
.. code-block:: none
#num_threads: i1
#cpu_threads: i1
where ``i1`` is the number of OpenMP threads to use. If ``#num_threads`` is not specified gprMax will firstly look to see if the environment variable ``OMP_NUM_THREADS`` exists, and if not will detect and use all available physical CPU cores on the machine.
where ``i1`` is the number of OpenMP threads to use. If ``#cpu_threads`` is not specified gprMax will firstly look to see if the environment variable ``OMP_NUM_THREADS`` exists, and if not will detect and use all available physical CPU cores on the machine.
.. _materials:
@@ -639,7 +628,7 @@ Allows you to insert pre-defined geometry into a model. The geometry is specifie
* The spatial resolution must be specified as a root attribute of the HDF5 file with the name ``dx_dy_dz`` equal to a tuple of floats, e.g. (0.002, 0.002, 0.002)
* If the geometry objects being imported were originally generated using gprMax, i.e. exported using #geometry_objects_write, then you can use dielectric smoothing as you like when generating the original geometry objects. However, if the geometry objects being imported were generated by an external method then dielectric smoothing will not take place.
For example, to insert a 2x2x2mm^3 AustinMan model with the lower left corner 40mm from the origin of the domain, and using disperive material properties use ``#geometry_objects_read: 0.04 0.04 0.04 ../user_libs/AustinManWoman/AustinMan_v2.3_2x2x2.h5 ../user_libs/AustinManWoman/AustinManWoman_materials_dispersive.txt``
For example, to insert a 2x2x2mm^3 AustinMan model with the lower left corner 40mm from the origin of the domain, and using disperive material properties use ``#geometry_objects_read: 0.04 0.04 0.04 toolboxes/AustinManWoman/AustinMan_v2.3_2x2x2.h5 toolboxes/AustinManWoman/AustinManWoman_materials_dispersive.txt``
#geometry_objects_write:
------------------------
@@ -691,7 +680,7 @@ For example, to specify the normalised first derivate of a Gaussian waveform wit
.. note::
* The functions used to create the waveforms can be found in the :ref:`tools section <waveforms>`.
* The functions used to create the waveforms can be found in the in ``toolboxes/Plotting`` package.
* ``gaussiandot``, ``gaussiandotnorm``, ``gaussiandotdot``, ``gaussiandotdotnorm``, ``ricker`` waveforms have their centre frequencies specified by the user, i.e. they are not derived to the 'base' ``gaussian``
* ``gaussianprime`` and ``gaussiandoubleprime`` waveforms are the first derivative and second derivative of the 'base' ``gaussian`` waveform, i.e. the centre frequencies of the waveforms will rise for the first and second derivatives.
@@ -814,11 +803,11 @@ Allows you to introduce a one-dimensional transmission line model [MAL1994]_ at
* ``f5 f6`` are optional parameters. ``f5`` is a time delay in starting the excitation of the transmission line. ``f6`` is a time to remove the excitation of the transmission line. If the time window is longer than the excitation of the transmission line removal time then the excitation of the transmission line will stop after the excitation of the transmission line removal time. If the excitation of the transmission line removal time is longer than the time window then the excitation of the transmission line will be active for the entire time window. If ``f5 f6`` are omitted the excitation of the transmission line will start at the beginning of time window and stop at the end of the time window.
* ``str1`` is the identifier of the waveform that should be used with the source.
Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`output file section <output>`. These parameters are useful for calculating characteristics of an antenna such as the input impedance or S-parameters. gprMax includes a Python module (in the ``tools`` package) to help you view the input impedance and s11 parameter from an antenna model fed using a transmission line. Details of how to use this module is given in the :ref:`tools section <plotting>`.
Time histories of voltage and current values in the transmission line are saved to the output file. These are documented in the :ref:`Simulation Output <output>` section. These parameters are useful for calculating characteristics of an antenna such as the input impedance or S-parameters. gprMax includes a Python module (in the ``toolboxes/Plotting`` package) to help you view the input impedance and s11 parameter from an antenna model fed using a transmission line.
For example, to specify a z directed transmission line source with a resistance of 75 Ohms, an amplitude of five, and a 1.2 GHz centre frequency Gaussian waveform use: ``#waveform: gaussian 5 1.2e9 my_gauss_pulse`` and ``#transmission_line: z 0.05 0.05 0.05 75 my_gauss_pulse``.
An example antenna model using a transmission line can be found in the :ref:`examples section <example-wire-dipole>`.
An example antenna model using a transmission line can be found in the :ref:`examples <example-wire-dipole>` section.
#rx:
----
@@ -864,7 +853,6 @@ Provides a simple method to allow you to move the location of all simple sources
.. note::
* ``#src_steps`` and ``#rx_steps`` are not suitable for moving sources which have associated geometry, e.g. antenna models.
* Values for ``#src_steps`` and ``#rx_steps`` should not be changed between model runs using Python scripting.
#snapshot:
----------
@@ -890,22 +878,13 @@ or
For example to save a snapshot of the electromagnetic fields in the model at a simulated time of 3 nanoseconds use: ``#snapshot: 0 0 0 1 1 1 0.1 0.1 0.1 3e-9 snap1``
.. 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 ``x1 y1 z1 x2 y2 z2 dx dy dz`` accordingly.
A series of snapshots can be more easily defined using a loop and our :ref:`Python API <input_api>`, see :ref:`outputs-snaps`.
.. code-block:: none
#python:
for i in range(1, 31):
print('#snapshot: x1 y1 z1 x2 y2 z2 dx dy dz {} snapshot{}'.format((i/10)*1e-9, i))
#end_python:
.. _pml-commands:
PML commands
============
The default behaviour for the absorbing boundary conditions (ABC) is first order Complex Frequency Shifted (CFS) Perfectly Matched Layers (PML), with thicknesses of 10 cells on each of the six sides of the model domain. This can be altered by using the following commands.
The default behaviour for the absorbing boundary conditions (ABC) is first order Complex Frequency Shifted (CFS) Perfectly Matched Layers (PML), with thicknesses of 10 cells on each of the six sides of the model domain. The thickness of the PML can be altered by using the following command (further customisation of the PML is possible using our Python API):
#pml_cells:
------------
@@ -928,47 +907,4 @@ For example to use a PML with 20 cells (thicker than the default 10 cells) on on
.. code-block:: none
#pml_cells: 10 10 20 10 10 20
#pml_formulation:
-----------------
Allows you to alter the formulation used for the PML. The current options are to use the Higher Order RIPML (HORIPML) - https://doi.org/10.1109/TAP.2011.2180344, or Multipole RIPML (MRIPML) - https://doi.org/10.1109/TAP.2018.2823864. The syntax of the command is:
.. code-block:: none
#pml_formulation: str
* ``str`` can be either 'HORIPML' or 'MRIPML'
For example to use the Multipole RIPML:
.. code-block:: none
#pml_formulation: MRIPML
#pml_cfs:
---------
Allows you (advanced) control of the parameters that are used to build each order of the PML. Up to a second order PML can currently be specified, i.e. by using two ``#pml_cfs`` commands. The syntax of the command is:
.. code-block:: none
#pml_cfs: str1 str2 f1 f2 str3 str4 f3 f4 str5 str6 f5 f6
* ``str1`` is the type of scaling to use for the CFS :math:`\alpha` parameter. It can be ``constant``, ``linear``, ``quadratic``, ``cubic``, ``quartic``, ``quintic`` and ``sextic``.
* ``str2`` is the direction of the scaling to use for the CFS :math:`\alpha` parameter. It can be ``forward`` or ``reverse``.
* ``f1 f2`` are the minimum and maximum values for the CFS :math:`\alpha` parameter.
* ``str3`` is the type of scaling to use for the CFS :math:`\kappa` parameter. It can be ``constant``, ``linear``, ``quadratic``, ``cubic``, ``quartic``, ``quintic`` and ``sextic``.
* ``str4`` is the direction of the scaling to use for the CFS :math:`\kappa` parameter. It can be ``forward`` or ``reverse``.
* ``f3 f4`` are the minimum and maximum values for the CFS :math:`\kappa` parameter. The minimum value for the CFS :math:`\kappa` parameter is one.
* ``str5`` is the type of scaling to use for the CFS :math:`\sigma` parameter. It can be ``constant``, ``linear``, ``quadratic``, ``cubic``, ``quartic``, ``quintic`` and ``sextic``.
* ``str6`` is the direction of the scaling to use for the CFS :math:`\sigma` parameter. It can be ``forward`` or ``reverse``.
* ``f5 f6`` are the minimum and maximum values for the CFS :math:`\sigma` parameter.
The CFS values (which are internally specified) used for the default standard first order PML are: ``#pml_cfs: constant forward 0 0 constant forward 1 1 quartic forward 0 None``. Specifying 'None' for the maximum value of :math:`\sigma` forces gprMax to calculate it internally based on the relative permittivity and permeability of the underlying materials in the model.
The parameters will be applied to all slabs of the PML that are switched on.
.. tip::
``forward`` direction implies minimum parameter value at the inner boundary of the PML and maximum parameter value at the edge of computational domain, ``reverse`` is the opposite.
#pml_cells: 10 10 20 10 10 20