From 29652cb8967c14af511fcdc46044b2374a53584a Mon Sep 17 00:00:00 2001 From: Craig Warren Date: Thu, 30 Mar 2023 10:19:26 +0100 Subject: [PATCH] Updated titles and intro text --- docs/source/input_api.rst | 18 +++++++++++++----- docs/source/input_hash_cmds.rst | 25 ++++++++++++++----------- 2 files changed, 27 insertions(+), 16 deletions(-) diff --git a/docs/source/input_api.rst b/docs/source/input_api.rst index 3c8fa1e4..ec224e16 100644 --- a/docs/source/input_api.rst +++ b/docs/source/input_api.rst @@ -1,18 +1,26 @@ .. _api: ************************************** -Model Building - advanced (Python API) +Model Building (Advanced - Python API) ************************************** Introduction ============ -In additional to input file command interface gprMax can also be run using its API. The usage of the API differs from the use of the Python blocks syntax as follows. In the API gprMax functionality is called directly from any Python file via the gprMax module. Using the Python blocks syntax the Python code is executed within an embedded interpreter. The API has the advantage that it can be included within any Python file and can be included within any Python script. -There are several advantages to using API. Firstly, users can take advantage of the Python language. For instance, the structural elements of Python can be utilised more easily. gprMax objects can be used directly within functions, classes, modules and packages. In this way collections of components can be defined, reused and modified. For example, multiple SMA type connectors can be imported as a module and combined with an antenna from another module. +gprMax has a choice of two methods for building a model to simulate: -The API also allows gprMax to interface with other Python libraries. For example, the API could be used to create a parametric antenna and the external library Scipy could then be used to optimise its parameters. Although, this is possible using Python blocks syntax, the script file can also be debugged. +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 (``#``). +2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. -The syntax of the API is generally more verbose than the input file command syntax. However, for input file commands where there are an undefined number of parameters, such as adding dispersive properties, the user may find the API more manageable. +Beginners and those not familiar with Python are encouraged to use method 1 (text-based input file) which is described in the :ref:`` section. + +The Python API in gprMax allows users to access to gprMax functions directly from Python through importing the gprMax module. There are several advantages to using the API: + +1. Users can take advantage of the Python language - for instance, the structural elements of Python can be utilised more easily. +2. gprMax objects can be used directly within functions, classes, modules and packages. In this way collections of components can be defined, reused and modified. For example, complex targets can be imported from a separate module and combined with an antenna from another module. +3. The API can interface with other Python libraries. For example, the API could be used to create a parametric antenna and the external library Scipy could then be used to optimise its parameters. + +The syntax of the API is generally more verbose than the input file (hash) command syntax. However, for input file commands where there are an undefined number of parameters, such as adding dispersive properties, the user may find the API more manageable. Example ======= diff --git a/docs/source/input_hash_cmds.rst b/docs/source/input_hash_cmds.rst index 098cc2cb..7274cfa0 100644 --- a/docs/source/input_hash_cmds.rst +++ b/docs/source/input_hash_cmds.rst @@ -1,10 +1,20 @@ .. _commands: -*************************************** -Model Building - simple (hash commands) -*************************************** +************** +Model Building +************** -An input file has to be supplied to gprMax which should contain all the necessary information to run a GPR model. The input file is an ASCII text file which can be prepared with any text editor or word-processing program. In the input file the hash character (``#``) is reserved and is used to denote the beginning of a command which will be passed to gprMax. The general syntax of commands is: +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 (``#``). +2. A **Python API**, which includes all the functionality of method 1 as well as several more advanced features. + +Beginners and those not familiar with Python are encouraged to use method 1 (text-based input file) which is described in this section of the documentation. For those who prefer to use Python or want to access some of the advanced features you will find those documented in the :ref:`` section. + +The general syntax of the hash commands is: .. code-block:: none @@ -101,13 +111,6 @@ where :math:`t_w` is the time window in seconds, :math:`\Delta t` the time step, General commands ================ -.. _python: - -#python: and #end_python: -------------------------- - -Allows you to write blocks of Python code between ``#python`` and ``#end_python`` in the input file. The code is executed when the input file is read by gprMax. For further details see the :ref:`Python section `. - #include_file: --------------