CBlockGrid.md

@@ -2,7 +2,7 @@ Class CBlockGrid handles grid organised into a 3D AMR octal tree (forrest) of bl
 
 The grid can be read from hdf files (written by Flash) or ascii files (in prep). The file must include certain basic properties that can be read by function readPFMetadata. The remaining data (content of blocks) can be read by parts (by individual blocks and quantities) by function readBlocks.
 
-The CBlockGrid class includes functions that allow to trasform blocks to a given refinement level, calculate their slices and integrals in a given direction and insert block data into a uniform grid (class [CUniformGrid](CUniformGrid)): cuboid, plane or line segment, aligned with the axes of the grid. 
+The CBlockGrid class includes functions that allow to trasform blocks to a given refinement level, calculate their slices and integrals in a given direction and insert block data into a uniform grid (class [CUniformGrid](CUniformGrid)): cuboid, plane or line segment, aligned with the axes of the grid. The CBlockGrid is always 3-dimensional, its axes have indeces XAXIS, YAXIS and YAXIS; contrary to the uniform grid, which can be 1-, 2-, or 3-dimensional and its axes have indeces AXIS1, AXIS2 and AXIS3. The correspondence between the two systems of coordinates is controlled by the --mode command line argument.
 
 Basic grid properties 
 ---------------------
@@ -45,8 +45,8 @@ Reading from file
 
 Block transformation
 --------------------
-* blkSlice(b, normal, coord) - Returns a 2d slice from 3d block at a given position. Does not interpolate, just finds the closest coordinate and copies the data. Args: b is block number, normal is direction of the normal to the slicing plane, coord is a coordinate of the slicing plane. Ret: npa(dir1, dir2).
-* blkIntegrate(b, normal, rng, quans, weights) - Integrates a block along a given direction and returns a block with dimension smaller by one. Only certain quantities (given by list quans) are integrated. The integrated quantities are multiplied by number/array weights. Args: b is the block number; normal is a direction of the normal vector (to the plane); rng are ranges of integration npa(LO/HI); quans is a list of quantities (strings) to be integrated; and weights are integration weights - a number or npa with the same shape (appart form the last dimension - quantities) as the original block b. Ret: a block with shape (n1, n2, len(quans)) where n1 and n2 are dimensions of the original block in non-integration dimensions. 
+* blkCut(self, b, axord, pos) - Returns a cut (2d slice or 1d line segment) from 3d block at a given position. Does not interpolate, just finds the closest coordinate and copies the data. Args: b is block number, axord is an array (npa(3)) defining ordering of axes of the cut; pos is a 3 element list defining the position of the cutting object in the grid (None means this dimension has only 1 element in the AMR grid, "RANGE" means that it is copied, a number defines the position). Ret: npa(dir1[, dir2]) - cutting object: plane or line segment.
+* blkIntegrate(self, b, axord, pos, bbox, quans, weights) - Integrates a block along a given direction(s) and returns a block with smaller dimension. Only certain quantities (given by list quans) are integrated. The integrated quantities are multiplied by number/array weights. Args: b is the block number; axord is an array (npa(3)) defining ordering of axes of the cut; pos is a 3 element list defining the position of the cutting object in the grid (None means this dimension has only 1 element in the AMR grid, "RANGE" means that it is copied, a number defines the position); bbox is the bounding box of the integrated grid (npa(dir,LO/HI)) ; quans is a list of quantities (strings) to be integrated; and weights are integration weights - a number or npa with the same shape (appart form the last dimension - quantities) as the original block b. Ret: a block with shape (dir1[, dir2], len(quans)) where dir1, and dir2 are dimensions of the original block in non-integration dimensions. 
 * blkToRefLevel(blk, rlDiff, axes) - Converts block blk to a different resolution by changing its size by a power of 2 (both shrink and grow). The values are simply copied or deleted, no interpolation is made. Args: blk is a block (npa with appropriate dimension + 1), rlDiff is a difference in the refinement level (integer), argument axes defines along which coords the growth/shrinking should be made. Ret: new block (npa with the same dim as blk.
 
 
@@ -54,8 +54,7 @@ Interaction with uniform grid
 -----------------------------
 * createUniformGrid(dim, direction, pos, reflevel, quans, bbox) - Creates a uniform grid (class CUniformGrid) covering the AMR grid, with coordinates aligned with it, restricted with given arguments. Args: dim - dimension (1, 2 or 3); direction - normal to the plane (for 2d) or direction vector (for 1d); pos - position of the plane (2d, one coordinate) or the line segment (1d, two coma-separated coordines); reflevel - refinement level determining size of UG cells; quans - quantities to be stored in the UG, encapsulated in the CQList object; bbox - bounding box, npa(dir,LO/HI).
 * insRanges(axis, bounds, ncells) - Determines sets of indices in a block (bIdx) and in an axis (aIdx) for the situation when a block (defined with bounds and ncells) is inserted into a uniform grid (defined with axis). Args: axis - axis of a uniform grid; bounds - min & max of an inserted block along the given axis; ncells - number of cells of a block in a given direction. Ret: tuple of two npa - bIdx and aIdx.
-* fillCuboid(cuboid) - Fills the 3d cuboid (CUniformGrid) with he block data. At first it determines which blocks and quantities will be needed depending on the grid's and plane's bbox. Then, it reads them from file, transforms them to the same rlevel as the uniform grid, and inserts them there. Args: cuboid is the 3D CUniformGrid object. Ret: None.
-* fillPlane(plane, integr, qn, plnQSlice, wn) - Fills the plane (CUniformGrid) with the block data. At first it determines which blocks and quantities will be needed depending on the grid's and plane's bbox and whether it should integrate in the third direction or just make a slice. Then, it reads the blocks from file, makes slices or integrals, transforms them to the same rlevel as the uniform grid, and inserts them into it. Args: plane is the 2D CUniformGrid object; integr is logical determining whether integrate (True) or make slice (False); qn is list of quantity names to be read and processed; and plnQSlice sets range of indeces in the plane where the quantities will be inserted. Ret: None.
+* Fills the uniform grid (CUniformGrid) with the block data. At first it determines which blocks and quantities will be needed depending on the AMR and uniform grid's bboxes and whether it should integrate in the other (two) directions or just make a cut. Then, it reads all necessary blocks from file, makes cuts or integrals, transforms them to the same rlevel as the uniform grid, and inserts them into it. Args: UG is the CUniformGrid object; integr is logical determining whether to integrate (True) or to make cut (False); qn is list of quantity names to be read and processed; UGQSlice sets range of indeces in the uniform grid where the quantities will be inserted; and wn is the name an eventual weighting quantity (integrals can be weighted). Ret: None.
 * ugAxis(direction, reflevel, bounds) - Creates an np array with grid cells coords along certain direction (0,1,2 = x, y, z), at a certain refinement level and restricted with bounds npa(2) - min, max).