From 65f129e7a84ccb616697f04b865ce6dbfd7af106 Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 3 Oct 2013 15:31:08 -0700 Subject: [PATCH] Documented utilities. --- SimPEG/utils/ModelBuilder.py | 25 ++++++++++++++----------- SimPEG/utils/__init__.py | 5 ++++- SimPEG/utils/lomutils.py | 27 +++++++++++---------------- SimPEG/utils/matutils.py | 4 ++-- docs/api_Utils.rst | 21 +++++++++++++++++++++ docs/index.rst | 9 +++++++++ 6 files changed, 61 insertions(+), 30 deletions(-) create mode 100644 docs/api_Utils.rst diff --git a/SimPEG/utils/ModelBuilder.py b/SimPEG/utils/ModelBuilder.py index 527d5eef..170da1bf 100644 --- a/SimPEG/utils/ModelBuilder.py +++ b/SimPEG/utils/ModelBuilder.py @@ -3,16 +3,18 @@ import numpy as np def getIndecesBlock(p0,p1,ccMesh): """ - Creates a vector containing the block indexes in the cell centerd mesh. - Returns a tuple + Creates a vector containing the block indexes in the cell centerd mesh. + Returns a tuple - The block is defined by the points - p0 : describe the position of the left upper front corner, and - p1 : describe the position of the right bottom back corner. + The block is defined by the points - ccMesh represents the cell-centered mesh + p0, describe the position of the left upper front corner, and - The points p0 and p1 must live in the the same dimensional space as the mesh. + p1, describe the position of the right bottom back corner. + + ccMesh represents the cell-centered mesh + + The points p0 and p1 must live in the the same dimensional space as the mesh. """ # Validation: p0 and p1 live in the same dimensional space @@ -64,9 +66,9 @@ def getIndecesBlock(p0,p1,ccMesh): def defineBlockConductivity(p0,p1,ccMesh,condVals): """ - Build a block with the conductivity specified by condVal. Returns an array. - condVals[0] conductivity of the block - condVals[1] conductivity of the ground + Build a block with the conductivity specified by condVal. Returns an array. + condVals[0] conductivity of the block + condVals[1] conductivity of the ground """ sigma = np.zeros(ccMesh.shape[0]) + condVals[1] ind = getIndecesBlock(p0,p1,ccMesh) @@ -80,7 +82,8 @@ def defineTwoLayeredConductivity(depth,ccMesh,condVals): Define a two layered model. Depth of the first layer must be specified. CondVals vector with the conductivity values of the layers. Eg: - Convention to number the layers: + Convention to number the layers:: + <----------------------------|------------------------------------> 0 depth zf 1st layer 2nd layer diff --git a/SimPEG/utils/__init__.py b/SimPEG/utils/__init__.py index bb46a4e9..7c976ce3 100644 --- a/SimPEG/utils/__init__.py +++ b/SimPEG/utils/__init__.py @@ -1,4 +1,7 @@ +import matutils +import sputils +import lomutils +import ModelBuilder from matutils import getSubArray, mkvc, ndgrid, ind2sub, sub2ind from sputils import spzeros, kron3, speye, sdiag from lomutils import volTetra, faceInfo, inv2X2BlockDiagonal, inv3X3BlockDiagonal, indexCube, exampleLomGird -import ModelBuilder diff --git a/SimPEG/utils/lomutils.py b/SimPEG/utils/lomutils.py index cdd6e0de..9020ce12 100644 --- a/SimPEG/utils/lomutils.py +++ b/SimPEG/utils/lomutils.py @@ -31,19 +31,18 @@ def volTetra(xyz, A, B, C, D): """ Returns the volume for tetrahedras volume specified by the indexes A to D. + :param numpy.array xyz: X,Y,Z vertex vector + :param numpy.array A,B,C,D: vert index of the tetrahedra + :rtype: numpy.array + :return: V, volume of the tetrahedra - Input: - xyz - X,Y,Z vertex vector - A,B,C,D - vert index of the tetrahedra + Algorithm http://en.wikipedia.org/wiki/Tetrahedron#Volume - Output: - V - volume + .. math:: - Algorithm: http://en.wikipedia.org/wiki/Tetrahedron#Volume + V = {1 \over 3} A h - V = 1/3 A * h - - V = 1/6 | ( a - d ) o ( ( b - d ) X ( c - d ) ) | + V = {1 \over 6} | ( a - d ) \cdot ( ( b - d ) ( c - d ) ) | """ @@ -69,7 +68,7 @@ def indexCube(nodes, gridSize, n=None): Output: index - index in the order asked e.g. 'ABCD' --> (A,B,C,D) - TWO DIMENSIONS: + TWO DIMENSIONS:: node(i,j) node(i,j+1) A -------------- B @@ -81,7 +80,7 @@ def indexCube(nodes, gridSize, n=None): node(i+1,j) node(i+1,j+1) - THREE DIMENSIONS: + THREE DIMENSIONS:: node(i,j,k+1) node(i,j+1,k+1) E --------------- F @@ -97,10 +96,6 @@ def indexCube(nodes, gridSize, n=None): D -------------- C node(i+1,j,k) node(i+1,j+1,k) - - @author Rowan Cockett - - Last modified on: 2013/07/26 """ assert type(nodes) == str, "Nodes must be a str variable: e.g. 'ABCD'" @@ -211,7 +206,7 @@ def faceInfo(xyz, A, B, C, D, average=True, normalizeNormals=True): # # So also could be viewed as the average parallelogram. # - # WARNING: This does not compute correctly for concave quadrilaterals + # TODO: This does not compute correctly for concave quadrilaterals area = (length(nA)+length(nB)+length(nC)+length(nD))/4 return N, area diff --git a/SimPEG/utils/matutils.py b/SimPEG/utils/matutils.py index 20cc33df..24286cdd 100644 --- a/SimPEG/utils/matutils.py +++ b/SimPEG/utils/matutils.py @@ -4,7 +4,7 @@ import numpy as np def mkvc(x, numDims=1): """Creates a vector with the number of dimension specified - e.g.: + e.g.:: a = np.array([1, 2, 3]) @@ -43,7 +43,7 @@ def ndgrid(*args, **kwargs): The inputs can be a list or separate arguments. - e.g. + e.g.:: a = np.array([1, 2, 3]) b = np.array([1, 2]) diff --git a/docs/api_Utils.rst b/docs/api_Utils.rst new file mode 100644 index 00000000..e952010b --- /dev/null +++ b/docs/api_Utils.rst @@ -0,0 +1,21 @@ +.. _api_Utils: + +Utilities +********* + +.. automodule:: SimPEG.utils.matutils + :members: + :undoc-members: + +.. automodule:: SimPEG.utils.sputils + :members: + :undoc-members: + +.. automodule:: SimPEG.utils.lomutils + :members: + :undoc-members: + +.. automodule:: SimPEG.utils.ModelBuilder + :members: + :undoc-members: + diff --git a/docs/index.rst b/docs/index.rst index b08624d5..4c01c4cd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -55,6 +55,15 @@ Testing SimPEG api_Tests +Utility Codes +============= + +.. toctree:: + :maxdepth: 2 + + api_Utils + + Project Index & Search ======================