diff --git a/gprMax/fractals.py b/gprMax/fractals.py
index 612f1031..ea49057e 100644
--- a/gprMax/fractals.py
+++ b/gprMax/fractals.py
@@ -58,7 +58,7 @@ class FractalSurface(object):
def generate_fractal_surface(self, G):
"""Generate a 2D array with a fractal distribution.
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -135,7 +135,7 @@ class FractalVolume(object):
def generate_fractal_volume(self, G):
"""Generate a 3D volume with a fractal distribution.
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -216,11 +216,11 @@ class Grass(object):
def calculate_blade_geometry(self, blade, height):
"""Calculates the x and y coordinates for a given height of grass blade.
-
+
Args:
blade (int): Numeric ID of grass blade.
height (float): Height of grass blade.
-
+
Returns:
x, y (float): x and y coordinates of grass blade.
"""
@@ -234,11 +234,11 @@ class Grass(object):
def calculate_root_geometry(self, root, depth):
"""Calculates the x and y coordinates for a given depth of grass root.
-
+
Args:
root (int): Numeric ID of grass root.
depth (float): Depth of grass root.
-
+
Returns:
x, y (float): x and y coordinates of grass root.
"""
diff --git a/gprMax/input_cmd_funcs.py b/gprMax/input_cmd_funcs.py
index c4f51f8b..91d00ffb 100644
--- a/gprMax/input_cmd_funcs.py
+++ b/gprMax/input_cmd_funcs.py
@@ -137,7 +137,7 @@ def geometry_view(xs, ys, zs, xf, yf, zf, dx, dy, dz, filename, type='n'):
dx, dy, dz (float): Spatial discretisation of geometry view.
filename (str): Filename where geometry file information will be stored.
type (str): Can be either n (normal) or f (fine) which specifies whether to output the geometry information on a per-cell basis (n) or a per-cell-edge basis (f).
-
+
Returns:
s, f, d (tuple): 3 namedtuple Coordinate for the start, finish coordinates and spatial discretisation
"""
@@ -157,7 +157,7 @@ def snapshot(xs, ys, zs, xf, yf, zf, dx, dy, dz, time, filename):
dx, dy, dz (float): Spatial discretisation of geometry view.
time (float): Time in seconds (float) or the iteration number (integer) which denote the point in time at which the snapshot will be taken.
filename (str): Filename where geometry file information will be stored.
-
+
Returns:
s, f, d (tuple): 3 namedtuple Coordinate for the start, finish coordinates and spatial discretisation
"""
@@ -181,7 +181,7 @@ def edge(xs, ys, zs, xf, yf, zf, material):
Args:
xs, ys, zs, xf, yf, zf (float): Start and finish coordinates.
material (str): Material identifier.
-
+
Returns:
s, f (tuple): 2 namedtuple Coordinate for the start and finish coordinates
"""
@@ -198,7 +198,7 @@ def plate(xs, ys, zs, xf, yf, zf, material):
Args:
xs, ys, zs, xf, yf, zf (float): Start and finish coordinates.
material (str): Material identifier(s).
-
+
Returns:
s, f (tuple): 2 namedtuple Coordinate for the start and finish coordinates
"""
@@ -216,7 +216,7 @@ def triangle(x1, y1, z1, x2, y2, z2, x3, y3, z3, thickness, material):
x1, y1, z1, x2, y2, z2, x3, y3, z3 (float): Coordinates of the vertices.
thickness (float): Thickness for a triangular prism, or zero for a triangular patch.
material (str): Material identifier(s).
-
+
Returns:
v1, v2, v3 (tuple): 3 namedtuple Coordinate for the vertices
"""
@@ -304,7 +304,7 @@ def excitation_file(file1):
Args:
file1 (str): filename
-
+
Returns:
file1 (str): filename
"""
@@ -321,7 +321,7 @@ def waveform(shape, amplitude, frequency, identifier):
amplitude (float): is the amplitude of the waveform.
frequency (float): is the frequency of the waveform in Hertz.
identifier (str): is an identifier for the waveform used to assign it to a source.
-
+
Returns:
identifier (str): is an identifier for the waveform used to assign it to a source.
"""
@@ -339,7 +339,7 @@ def hertzian_dipole(polarization, f1, f2, f3, identifier, t0=None, t_remove=None
identifier (str): is the identifier of the waveform that should be used with the source.
t0 (float): is an optinal argument for the time delay in starting the source.
t_remove (float): is a time to remove the source.
-
+
Returns:
coordinates (tuple): namedtuple Coordinate of the source location
"""
@@ -357,7 +357,7 @@ def rx(x, y, z, identifier=None, to_save=None):
x, y, z (float): are the coordinates (x,y,z) of the receiver in the model.
identifier (str): is the optional identifier of the receiver
to_save (list): is a list of outputs with this receiver. It can be any selection from 'Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz', 'Ix', 'Iy', or 'Iz'.
-
+
Returns:
coordinates (tuple): namedtuple Coordinate of the receiver location
"""
@@ -372,7 +372,7 @@ def src_steps(dx=0, dy=0, dz=0):
Args:
dx, dy, dz (float): are the increments in (x, y, z) to move all simple sources or all receivers.
-
+
Returns:
coordinates (tuple): namedtuple Coordinate of the increments
"""
@@ -388,7 +388,7 @@ def rx_steps(dx=0, dy=0, dz=0):
Args:
dx, dy, dz (float): are the increments in (x, y, z) to move all simple sources or all receivers.
-
+
Returns:
coordinates (tuple): namedtuple Coordinate of the increments
"""
diff --git a/gprMax/input_cmds_file.py b/gprMax/input_cmds_file.py
index fbde599c..d71b3a2c 100644
--- a/gprMax/input_cmds_file.py
+++ b/gprMax/input_cmds_file.py
@@ -25,11 +25,11 @@ from gprMax.exceptions import CmdInputError
def process_python_include_code(inputfile, usernamespace):
"""Looks for and processes any Python code found in the input file. It will ignore any lines that are comments, i.e. begin with a double hash (##), and any blank lines. It will also ignore any lines that do not begin with a hash (#) after it has processed Python commands. It will also process any include commands and insert the contents of the included file at that location.
-
+
Args:
inputfile (str): Name of the input file to open.
usernamespace (dict): Namespace that can be accessed by user in any Python code blocks in input file.
-
+
Returns:
processedlines (list): Input commands after Python processing.
"""
@@ -118,7 +118,7 @@ def process_python_include_code(inputfile, usernamespace):
def write_processed_file(inputfile, modelrun, numbermodelruns, processedlines):
"""Writes an input file after any Python code and include commands in the original input file have been processed.
-
+
Args:
inputfile (str): Name of the input file to open.
modelrun (int): Current model run number.
@@ -140,11 +140,11 @@ def write_processed_file(inputfile, modelrun, numbermodelruns, processedlines):
def check_cmd_names(processedlines, checkessential=True):
"""Checks the validity of commands, i.e. are they gprMax commands, and that all essential commands are present.
-
+
Args:
processedlines (list): Input commands after Python processing.
checkessential (boolean): Perform check to see that all essential commands are present.
-
+
Returns:
singlecmds (dict): Commands that can only occur once in the model.
multiplecmds (dict): Commands that can have multiple instances in the model.
diff --git a/gprMax/input_cmds_geometry.py b/gprMax/input_cmds_geometry.py
index be7ebec3..d23e3d02 100644
--- a/gprMax/input_cmds_geometry.py
+++ b/gprMax/input_cmds_geometry.py
@@ -33,10 +33,10 @@ from gprMax.utilities import round_value
def process_geometrycmds(geometry, G):
"""This function checks the validity of command parameters, creates instances of classes of parameters, and calls functions to directly set arrays solid, rigid and ID.
-
+
Args:
geometry (list): Geometry commands in the model
-
+
"""
for object in geometry:
diff --git a/gprMax/input_cmds_singleuse.py b/gprMax/input_cmds_singleuse.py
index 9466a8e1..29c6af53 100644
--- a/gprMax/input_cmds_singleuse.py
+++ b/gprMax/input_cmds_singleuse.py
@@ -30,7 +30,7 @@ from gprMax.waveforms import Waveform
def process_singlecmds(singlecmds, G):
"""Checks the validity of command parameters and creates instances of classes of parameters.
-
+
Args:
singlecmds (dict): Commands that can only occur once in the model.
G (class): Grid class instance - holds essential parameters describing the model.
diff --git a/gprMax/materials.py b/gprMax/materials.py
index 5b97e4c8..76b3835c 100644
--- a/gprMax/materials.py
+++ b/gprMax/materials.py
@@ -69,7 +69,7 @@ class Material(object):
def calculate_update_coeffsH(self, G):
"""Calculates the magnetic update coefficients of the material.
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -85,7 +85,7 @@ class Material(object):
# Calculate electric update coefficients
def calculate_update_coeffsE(self, G):
"""Calculates the electric update coefficients of the material.
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -167,7 +167,7 @@ class PeplinskiSoil(object):
def calculate_debye_properties(self, nbins, G):
"""Calculates the real and imaginery part of a Debye model for the soil as well as a conductivity. It uses a semi-empirical model (http://dx.doi.org/10.1109/36.387598).
-
+
Args:
nbins (int): Number of bins to use to create the different materials.
G (class): Grid class instance - holds essential parameters describing the model.
diff --git a/gprMax/optimisation_taguchi.py b/gprMax/optimisation_taguchi.py
index 860623be..5f4d127a 100644
--- a/gprMax/optimisation_taguchi.py
+++ b/gprMax/optimisation_taguchi.py
@@ -30,7 +30,7 @@ from gprMax.gprMax import run_std_sim, run_mpi_sim
def run_opt_sim(args, numbermodelruns, inputfile, usernamespace):
"""Run a simulation using Taguchi's optmisation process.
-
+
Args:
args (dict): Namespace with command line arguments
numbermodelruns (int): Total number of model runs.
@@ -159,11 +159,11 @@ def run_opt_sim(args, numbermodelruns, inputfile, usernamespace):
def taguchi_code_blocks(inputfile, taguchinamespace):
"""Looks for and processes a Taguchi code block (containing Python code) in the input file. It will ignore any lines that are comments, i.e. begin with a double hash (##), and any blank lines.
-
+
Args:
inputfile (str): Name of the input file to open.
taguchinamespace (dict): Namespace that can be accessed by user a Taguchi code block in input file.
-
+
Returns:
processedlines (list): Input commands after Python processing.
"""
@@ -205,10 +205,10 @@ def taguchi_code_blocks(inputfile, taguchinamespace):
def construct_OA(optparams):
"""Load an orthogonal array (OA) from a numpy file. Configure and return OA and properties of OA.
-
+
Args:
optparams (dict): Dictionary containing name of parameters to optimise and their initial ranges
-
+
Returns:
OA (array): Orthogonal array
N (int): Number of experiments in OA
@@ -292,7 +292,7 @@ def construct_OA(optparams):
def calculate_ranges_experiments(optparams, optparamsinit, levels, levelsopt, levelsdiff, OA, N, k, s, i):
"""Calculate values for parameters to optimise for a set of experiments.
-
+
Args:
optparams (dict): Ordered dictionary containing name of parameters to optimise and their values
optparamsinit (list): Initial ranges for parameters to optimise
@@ -304,7 +304,7 @@ def calculate_ranges_experiments(optparams, optparamsinit, levels, levelsopt, le
k (int): Number of parameters to optimise in OA
s (int): Number of levels in OA
i (int): Iteration number
-
+
Returns:
optparams (dict): Ordered dictionary containing name of parameters to optimise and their values
levels (array): Lower, central, and upper values for each parameter
@@ -359,7 +359,7 @@ def calculate_ranges_experiments(optparams, optparamsinit, levels, levelsopt, le
def calculate_optimal_levels(optparams, levels, levelsopt, fitnessvalues, OA, N, k):
"""Calculate optimal levels from results of fitness metric by building a response table.
-
+
Args:
optparams (dict): Ordered dictionary containing name of parameters to optimise and their values
levels (array): Lower, central, and upper values for each parameter
@@ -368,7 +368,7 @@ def calculate_optimal_levels(optparams, levels, levelsopt, fitnessvalues, OA, N,
OA (array): Orthogonal array
N (int): Number of experiments in OA
k (int): Number of parameters to optimise in OA
-
+
Returns:
optparams (dict): Ordered dictionary containing name of parameters to optimise and their values
levelsopt (array): Optimal level for each parameter from previous iteration
@@ -417,7 +417,7 @@ def calculate_optimal_levels(optparams, levels, levelsopt, fitnessvalues, OA, N,
def plot_optimisation_history(fitnessvalueshist, optparamshist, optparamsinit):
"""Plot the history of fitness values and each optimised parameter values for the optimisation.
-
+
Args:
fitnessvalueshist (list): History of fitness values
optparamshist (dict): Name of parameters to optimise and history of their values
diff --git a/gprMax/pml.py b/gprMax/pml.py
index 451eb2ed..8911f37d 100644
--- a/gprMax/pml.py
+++ b/gprMax/pml.py
@@ -66,7 +66,7 @@ class CFS(object):
def calculate_sigmamax(self, direction, er, mr, G):
"""Calculates an optimum value for sigma max based on underlying material properties.
-
+
Args:
direction (str): Direction of PML slab
er (float): Average permittivity of underlying material.
@@ -87,12 +87,12 @@ class CFS(object):
def scaling_polynomial(self, order, Evalues, Hvalues):
"""Applies the polynomial to be used for the scaling profile for electric and magnetic PML updates.
-
+
Args:
order (int): Order of polynomial for scaling profile.
Evalues (float): numpy array holding scaling profile values for electric PML update.
Hvalues (float): numpy array holding scaling profile values for magnetic PML update.
-
+
Returns:
Evalues (float): numpy array holding scaling profile values for electric PML update.
Hvalues (float): numpy array holding scaling profile values for magnetic PML update.
@@ -105,11 +105,11 @@ class CFS(object):
def calculate_values(self, thickness, parameter):
"""Calculates values for electric and magnetic PML updates based on profile type and minimum and maximum values.
-
+
Args:
thickness (int): Thickness of PML in cells.
parameter (CFSParameter): Instance of CFSParameter
-
+
Returns:
Evalues (float): numpy array holding profile value for electric PML update.
Hvalues (float): numpy array holding profile value for magnetic PML update.
@@ -194,7 +194,7 @@ class PML(object):
def calculate_update_coeffs(self, er, mr, G):
"""Calculates electric and magnetic update coefficients for the PML.
-
+
Args:
er (float): Average permittivity of underlying material
mr (float): Average permeability of underlying material
diff --git a/gprMax/snapshots.py b/gprMax/snapshots.py
index 3984ea21..ab32f513 100644
--- a/gprMax/snapshots.py
+++ b/gprMax/snapshots.py
@@ -67,7 +67,7 @@ class Snapshot(object):
def prepare_vtk_imagedata(self, modelrun, numbermodelruns, G):
"""Prepares a VTK ImageData (.vti) file for a snapshot.
-
+
Args:
modelrun (int): Current model run number.
numbermodelruns (int): Total number of model runs.
@@ -112,7 +112,7 @@ class Snapshot(object):
def write_vtk_imagedata(self, Ex, Ey, Ez, Hx, Hy, Hz, G):
"""Writes electric and magnetic field values to VTK ImageData (.vti) file.
-
+
Args:
Ex, Ey, Ez, Hx, Hy, Hz (memory view): Electric and magnetic field values.
G (class): Grid class instance - holds essential parameters describing the model.
diff --git a/gprMax/sources.py b/gprMax/sources.py
index 7e3fabbe..b893aca4 100644
--- a/gprMax/sources.py
+++ b/gprMax/sources.py
@@ -51,7 +51,7 @@ class VoltageSource(Source):
def update_electric(self, abstime, updatecoeffsE, ID, Ex, Ey, Ez, G):
"""Updates electric field values for a voltage source.
-
+
Args:
abstime (float): Absolute time.
updatecoeffsE (memory view): numpy array of electric field update coefficients.
@@ -91,7 +91,7 @@ class VoltageSource(Source):
def create_material(self, G):
"""Create a new material at the voltage source location that adds the voltage source conductivity to the underlying parameters.
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -129,7 +129,7 @@ class HertzianDipole(Source):
def update_electric(self, abstime, updatecoeffsE, ID, Ex, Ey, Ez, G):
"""Updates electric field values for a Hertzian dipole.
-
+
Args:
abstime (float): Absolute time.
updatecoeffsE (memory view): numpy array of electric field update coefficients.
@@ -167,7 +167,7 @@ class MagneticDipole(Source):
def update_magnetic(self, abstime, updatecoeffsH, ID, Hx, Hy, Hz, G):
"""Updates magnetic field values for a magnetic dipole.
-
+
Args:
abstime (float): Absolute time.
updatecoeffsH (memory view): numpy array of magnetic field update coefficients.
@@ -231,7 +231,7 @@ class TransmissionLine(Source):
def calculate_incident_V_I(self, G):
"""Calculates the incident voltage and current with a long length transmission line not connected to the main grid from: http://dx.doi.org/10.1002/mop.10415
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -250,7 +250,7 @@ class TransmissionLine(Source):
def update_abc(self, G):
"""Updates absorbing boundary condition at end of the transmission line.
-
+
Args:
G (class): Grid class instance - holds essential parameters describing the model.
"""
@@ -263,7 +263,7 @@ class TransmissionLine(Source):
def update_voltage(self, time, G):
"""Updates voltage values along the transmission line.
-
+
Args:
time (float): Absolute time.
G (class): Grid class instance - holds essential parameters describing the model.
@@ -281,7 +281,7 @@ class TransmissionLine(Source):
def update_current(self, time, G):
"""Updates current values along the transmission line.
-
+
Args:
time (float): Absolute time.
G (class): Grid class instance - holds essential parameters describing the model.
@@ -296,7 +296,7 @@ class TransmissionLine(Source):
def update_electric(self, abstime, Ex, Ey, Ez, G):
"""Updates electric field value in the main grid from voltage value in the transmission line.
-
+
Args:
abstime (float): Absolute time.
Ex, Ey, Ez (memory view): numpy array of electric field values.
@@ -323,7 +323,7 @@ class TransmissionLine(Source):
def update_magnetic(self, abstime, Hx, Hy, Hz, G):
"""Updates current value in transmission line from magnetic field values in the main grid.
-
+
Args:
abstime (float): Absolute time.
Hx, Hy, Hz (memory view): numpy array of magnetic field values.
diff --git a/gprMax/utilities.py b/gprMax/utilities.py
index d47e431d..6e84d2f7 100644
--- a/gprMax/utilities.py
+++ b/gprMax/utilities.py
@@ -22,7 +22,7 @@ import decimal as d
def logo(version):
"""Print gprMax logo, version, and licencing/copyright information.
-
+
Args:
version (str): Version number.
"""
@@ -30,17 +30,17 @@ def logo(version):
licenseinfo = """
Copyright (C) 2015-2016: The University of Edinburgh
Authors: Craig Warren and Antonis Giannopoulos
-
+
gprMax is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
-
+
gprMax is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
-
+
You should have received a copy of the GNU General Public License
along with gprMax. If not, see ."""
@@ -65,7 +65,7 @@ along with gprMax. If not, see ."""
def update_progress(progress):
"""Displays or updates a console progress bar.
-
+
Args:
progress (float): Number between zero and one to signify progress.
"""
@@ -80,11 +80,11 @@ def update_progress(progress):
def round_value(value, decimalplaces=0):
"""Rounding function.
-
+
Args:
value (float): Number to round.
decimalplaces (int): Number of decimal places of float to represent rounded value.
-
+
Returns:
rounded (int/float): Rounded value.
"""
@@ -103,11 +103,11 @@ def round_value(value, decimalplaces=0):
def human_size(size, a_kilobyte_is_1024_bytes=True):
"""Convert a file size to human-readable form.
-
+
Args:
size (int): file size in bytes
a_kilobyte_is_1024_bytes (boolean) - true for multiples of 1024, false for multiples of 1000
-
+
Returns:
Human-readable (string).
"""
diff --git a/gprMax/waveforms.py b/gprMax/waveforms.py
index 57e26b82..d08c13ed 100644
--- a/gprMax/waveforms.py
+++ b/gprMax/waveforms.py
@@ -35,11 +35,11 @@ class Waveform(object):
def calculate_value(self, time, dt):
"""Calculates value of the waveform at a specific time.
-
+
Args:
time (float): Absolute time.
dt (float): Absolute time discretisation.
-
+
Returns:
waveform (float): Calculated value for waveform.
"""