From 0b4f26d1fe73fc4472519466678ef7eb95262ad2 Mon Sep 17 00:00:00 2001 From: John Hartley Date: Sat, 24 Aug 2019 12:22:20 +0100 Subject: [PATCH] comments for geometry building commands --- gprMax/cmds_geometry/add_grass.py | 16 +++++++++++- gprMax/cmds_geometry/add_surface_roughness.py | 18 ++++++++++++- gprMax/cmds_geometry/add_surface_water.py | 12 ++++++++- gprMax/cmds_geometry/box.py | 14 +++++++++- gprMax/cmds_geometry/cylinder.py | 15 ++++++++++- gprMax/cmds_geometry/cylindrical_sector.py | 26 ++++++++++++++++++- gprMax/cmds_geometry/edge.py | 10 ++++++- gprMax/cmds_geometry/fractal_box.py | 22 +++++++++++++++- gprMax/cmds_geometry/plate.py | 12 ++++++++- gprMax/cmds_geometry/sphere.py | 14 +++++++++- gprMax/cmds_geometry/triangle.py | 18 ++++++++++++- 11 files changed, 166 insertions(+), 11 deletions(-) diff --git a/gprMax/cmds_geometry/add_grass.py b/gprMax/cmds_geometry/add_grass.py index e17493f4..90c5b64f 100644 --- a/gprMax/cmds_geometry/add_grass.py +++ b/gprMax/cmds_geometry/add_grass.py @@ -11,7 +11,21 @@ import numpy as np class AddGrass(UserObjectGeometry): - """User class for Grass command.""" + """Allows you to add grass with roots to a :class:`FractalBox` in the model. + + :param p1: The lower left (x,y,z) coordinates of a surface on a :class:`FractalBox` + :type p1: list, non-optional + :param p2: The lower left (x,y,z) coordinates of a surface on a :class:`FractalBox` + :type p2: list, non-optional + :param frac_dim: is the fractal dimension which, for an orthogonal parallelepiped, should take values between zero and three. + :type frac_dim: float, non-optional + :param limits: Define lower and upper limits for a range over which the height of the blades of grass can vary. + :type limits: list, non-optional + :param n_blades: The number of blades of grass that should be applied to the surface area. + :type n_blades: int, non-optional + :param fractal_box_id: An identifier for the :class:`FractalBox` that the grass should be applied to + :type fractal_box_id: list, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/add_surface_roughness.py b/gprMax/cmds_geometry/add_surface_roughness.py index 90cd10b5..f8c12869 100644 --- a/gprMax/cmds_geometry/add_surface_roughness.py +++ b/gprMax/cmds_geometry/add_surface_roughness.py @@ -10,7 +10,23 @@ import numpy as np class AddSurfaceRoughness(UserObjectGeometry): - """User class for edge command.""" + """Allows you to add grass with roots to a :class:`FractalBox` in the model. + + :param p1: The lower left (x,y,z) coordinates of a surface on a :class:`FractalBox` + :type p1: list, non-optional + :param p2: The lower left (x,y,z) coordinates of a surface on a :class:`FractalBox` + :type p2: list, non-optional + :param frac_dim: is the fractal dimension which, for an orthogonal parallelepiped, should take values between zero and three. + :type frac_dim: float, non-optional + :param weighting: Weightings in the first and second direction of the surface. + :type weighting: list, non-optional + :param limits: Define lower and upper limits for a range over which the roughness can vary. + :type limits: list, non-optional + :param fractal_box_id: An identifier for the :class:`FractalBox` that the roughness should be applied to + :type fractal_box_id: list, non-optional + :param seed: Is an optional parameter which controls the seeding of the random number generator used to create the fractals. + :type seed: int, optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/add_surface_water.py b/gprMax/cmds_geometry/add_surface_water.py index 57b8de00..4dbe13e1 100644 --- a/gprMax/cmds_geometry/add_surface_water.py +++ b/gprMax/cmds_geometry/add_surface_water.py @@ -8,7 +8,17 @@ from tqdm import tqdm class AddSurfaceWater(UserObjectGeometry): - """User class for edge command.""" + """Allows you to add surface water to a :class:`FractalBox` in the model. + + :param p1: The lower left (x,y,z) coordinates of a surface on a :class:`FractalBox` + :type p1: list, non-optional + :param p2: The lower left (x,y,z) coordinates of a surface on a :class:`FractalBox` + :type p2: list, non-optional + :param depth: Defines the depth of the water, which should be specified relative to the dimensions of the #fractal_box that the surface water is being applied. + :type depth: float, non-optional + :param fractal_box_id: An identifier for the :class:`FractalBox` that the water should be applied to + :type fractal_box_id: list, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/box.py b/gprMax/cmds_geometry/box.py index c519cc8b..88db127f 100644 --- a/gprMax/cmds_geometry/box.py +++ b/gprMax/cmds_geometry/box.py @@ -10,7 +10,19 @@ import numpy as np class Box(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce an orthogonal parallelepiped with specific properties into the model. + + :param p1: The lower left (x,y,z) coordinates of a the box. + :type p1: list, non-optional + :param p2: The lower left (x,y,z) coordinates of the box. + :type p2: list, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + :param material_ids: Material identifiers in the x, y, z directions. + :type material_ids: list, non-optional + :param averaging: y or n, used to switch on and off dielectric smoothing. + :type averaging: str, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/cylinder.py b/gprMax/cmds_geometry/cylinder.py index 18936210..30d2fcb3 100644 --- a/gprMax/cmds_geometry/cylinder.py +++ b/gprMax/cmds_geometry/cylinder.py @@ -10,8 +10,21 @@ import gprMax.config as config class Cylinder(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce a circular cylinder into the model. + :param p1: The coordinates (x,y,z) of the centre of the first face of the cylinder. + :type p1: list, non-optional + :param p2: The coordinates (x,y,z) of the centre of the second face of the cylinder. + :type p2: list, non-optional + :param r: is the radius of the cylinder. + :type r: float, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + :param material_ids: Material identifiers in the x, y, z directions. + :type material_ids: list, non-optional + :param averaging: y or n, used to switch on and off dielectric smoothing. + :type averaging: str, non-optional + """ def __init__(self, **kwargs): """Constructor.""" super().__init__(**kwargs) diff --git a/gprMax/cmds_geometry/cylindrical_sector.py b/gprMax/cmds_geometry/cylindrical_sector.py index 082607cc..ad5702f1 100644 --- a/gprMax/cmds_geometry/cylindrical_sector.py +++ b/gprMax/cmds_geometry/cylindrical_sector.py @@ -9,7 +9,31 @@ import numpy as np class CylindricalSector(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce a cylindrical sector (shaped like a slice of pie) into the model. + + :param normal: Direction of the axis of the cylinder from which the sector is defined and can be x, y, or z.. + :type normal: str, non-optional + :param ctr1: First coordinate of the centre of the cylindrical sector. + :type ctr1: float, non-optional + :param ctr2: Second coordinate of the centre of the cylindrical sector. + :type ctr2: Float, non-optional + :param extent1: First thickness from the centre of the cylindrical sector. + :type extent1: float, non-optional + :param extent2: Second thickness from the centre of the cylindrical sector. + :type extent2: float, non-optional + :param r: is the radius of the cylindrical sector. + :type r: float, non-optional + :param start: The starting angle (in degrees) for the cylindrical sector. + :type start: float, non-optional + :param end: The angle (in degrees) swept by the cylindrical sector + :type end: float, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + :param material_ids: Material identifiers in the x, y, z directions. + :type material_ids: list, non-optional + :param averaging: y or n, used to switch on and off dielectric smoothing. + :type averaging: str, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/edge.py b/gprMax/cmds_geometry/edge.py index 691be9cf..a65ce990 100644 --- a/gprMax/cmds_geometry/edge.py +++ b/gprMax/cmds_geometry/edge.py @@ -9,7 +9,15 @@ from tqdm import tqdm class Edge(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce a wire with specific properties into the model. + + :param p1: Starting point of the edge. + :type p1: list, non-optional + :param p2: Ending point of the edge. + :type p2: list, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/fractal_box.py b/gprMax/cmds_geometry/fractal_box.py index c792bb51..3d346564 100644 --- a/gprMax/cmds_geometry/fractal_box.py +++ b/gprMax/cmds_geometry/fractal_box.py @@ -9,7 +9,27 @@ import numpy as np class FractalBox(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce an orthogonal parallelepiped with fractal distributed properties which are related to a mixing model or normal material into the model. + + :param p1: The lower left (x,y,z) coordinates of the parallelepiped + :type p1: list, non-optional + :param p2: The upper right (x,y,z) coordinates of the parallelepiped + :type p2: list, non-optional + :param frac_dim: The fractal dimension which, for an orthogonal parallelepiped, should take values between zero and three. + :type frac_dim: float, non-optional + :param weighting: Weightings in the x, y, z direction of the surface. + :type weighting: list, non-optional + :param n_materials: Number of materials to use for the fractal distribution (defined according to the associated mixing model). This should be set to one if using a normal material instead of a mixing model. + :type n_materials: list, non-optional + :param mixing_model_id: Is an identifier for the associated mixing model or material. + :type mixing_model_id: list, non-optional + :param id: Identifier for the fractal box itself. + :type id: list, non-optional + :param seed: Controls the seeding of the random number generator used to create the fractals.. + :type seed: float, non-optional + :param averaging: y or n, used to switch on and off dielectric smoothing. + :type averaging: str, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/plate.py b/gprMax/cmds_geometry/plate.py index 68a9b270..b908d0d8 100644 --- a/gprMax/cmds_geometry/plate.py +++ b/gprMax/cmds_geometry/plate.py @@ -9,7 +9,17 @@ from tqdm import tqdm class Plate(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce a plate with specific properties into the model. + + :param p1: The lower left (x,y,z) coordinates of the plate. + :type p1: list, non-optional + :param p2: The upper right (x,y,z) coordinates of the plate. + :type p2: list, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + :param material_ids: Material identifiers in the x, y, z directions. + :type material_ids: list, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/sphere.py b/gprMax/cmds_geometry/sphere.py index bea45f99..cf63fbd0 100644 --- a/gprMax/cmds_geometry/sphere.py +++ b/gprMax/cmds_geometry/sphere.py @@ -9,7 +9,19 @@ import numpy as np class Sphere(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce a spherical object with specific parameters into the model. + + :param p1: the coordinates (x,y,z) of the centre of the sphere. + :type p1: list, non-optional + :param r: The coordinates (x,y,z) of the centre of the sphere. + :type r: float, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + :param material_ids: Material identifiers in the x, y, z directions. + :type material_ids: list, non-optional + :param averaging: y or n, used to switch on and off dielectric smoothing. + :type averaging: str, non-optional + """ def __init__(self, **kwargs): """Constructor.""" diff --git a/gprMax/cmds_geometry/triangle.py b/gprMax/cmds_geometry/triangle.py index 89671aa1..b1bdc3ad 100644 --- a/gprMax/cmds_geometry/triangle.py +++ b/gprMax/cmds_geometry/triangle.py @@ -9,7 +9,23 @@ import numpy as np class Triangle(UserObjectGeometry): - """User class for edge command.""" + """Allows you to introduce a triangular patch or a triangular prism with specific properties into the model. + + :param p1: the coordinates (x,y,z) of the first apex of the triangle. + :type p1: list, non-optional + :param p2: the coordinates (x,y,z) of the second apex of the triangle + :type p2: list, non-optional + :param p3: the coordinates (x,y,z) of the third apex of the triangle. + :type p3: list, non-optional + :param thickness: The thickness of the triangular prism. If the thickness is zero then a triangular patch is created. + :type thickness: float, non-optional + :param material_id: Material identifier that must correspond to material that has already been defined. + :type material_id: str, non-optional + :param material_ids: Material identifiers in the x, y, z directions. + :type material_ids: list, non-optional + :param averaging: y or n, used to switch on and off dielectric smoothing. + :type averaging: str, non-optional + """ def __init__(self, **kwargs): """Constructor."""