==================================
``grail.data.partialsfile`` Module
==================================

.. include:: ..\..\version.h

.. contents:: Table of Contents
   :backlinks: top

--------
Overview
--------

A partials file is an ASCII file that represents the percentages of a solid
or polygon that falls within each block of a 3D block model.

This module is a read-only interface to the partials file format.  This module will
read a partials file for a solid (i.e. `mspart.out`) or a polygon (i.e. `ipres.out`)
and provide a convenient structure that you can iterate through to do calculations.
It is intended to be used in conjunction with the `grail.data.model`_.

.. _grail.data.model: ../lib-grail-data-model.html

--------
Examples
--------

The following snippet illustrates how to use a Partial object in conjunction with a Model
object in order to determine the total value represented by a cut.

.. Python::

   part = partialsfile.Partial("ipres.out")

   # get the PCF limits and block sizes
   p = pcf.Pcf(srcpcf)
   dx = p.dx()
   dy = p.dy()
   dz = p.dz()
   cellVolume = dx*dy*dz
   items = p.itemlist(srcmodel)

   # get the extents of the geometry represented in the partials file.
   xmin = part.colMin
   xmax = part.colMax
   ymin = part.rowMin
   ymax = part.rowMax
   zmin = part.levelMin
   zmax = part.levelMax

   # retrieve the minimum slab from block model
   m = model.Model(srcpcf, srcmodel, zmin, zmax, ymin, ymax, xmin, xmax, items)
   slab = m.slab()

   # iterate through each block contained by geometry and calculate tonnage
   totalVal=0
   for block in part.blockList:
      lvl = block.level
      row = block.row
      col = block.col
      pct = block.pct

      # Get the density item for the cell
      sg = slab.modget('SG', lvl, row, col)

      # Get the value per ton item for the cell
      value_per_ton = slab.modget('VALPT', lvl, row, col)

      # Calculate tons using percentage
      tons = (pct/100.0) * cellVolume * sg

      # Calculate the total value of that partial block
      val = tons * value_per_ton

      # accumulate value
      totalVal += val

   m.free()
   print "total value:", totalVal


-------
Partial
-------

:c:`Partial(file_path)`

   Partial is the top-level class.  The constructor takes the partials file path as it's only argument.

   **Methods**

      :df:`getTonnage(density, cellVolume)`

         Returns the tonnage of the cut given the cell size and a common density. Warning: if the S.G. fluctuates
         from block to block, it will be more accurate to use a method similar to the example above.


   **Attributes**

      :dd:`name`

         This is the path to the file.

      :dd:`blockList`

         A list of block objects (see below)

      :dd:`colMin`

         The minimum column number in the block model occupied by the geometry.

      :dd:`colMax`

         The maximum column number in the block model occupied by the geometry.

      :dd:`rowMin`

         The minimum row number in the block model occupied by the geometry.

      :dd:`rowMax`

         The maximum column number in the block model occupied by the geometry.

      :dd:`levelMin`

         The minimum level number in the block model occupied by the geometry.

      :dd:`levelMax`

         The minimum level number in the block model occupied by the geometry.

-------
Block
-------

:c:`Block`

   Block is an inner-class of Partial.  The Partial object contains a list of blocks.
   Each block object refers to one unique cell in the block model.

   **Attributes**


      :dd:`level`

         The cell's level in the Block Model.

      :dd:`row`

         The cell's row number in the Block Model.

      :dd:`col`

         The cell's column number in the Block Model.

      :dd:`pct`

         The percentage volume of the cell occupied by the geometry.