**************************************
itm.grid.cpo - High-level CPO handling
**************************************

The classes and functions in this module simplify basic access to CPOs.

.. contents::

Handling CPOs: The Cpo wrapper class
====================================

Basic CPO access
----------------

Typically, to get a CPO from the UAL, one writes::

	import ual
	itm = ual.itm(17151, 4)
	itm.open_env('klingshi', 'aug', '4.09a')
	itm.edge.getSlice(2.5, ual.ualdef.CLOSEST_SAMPLE)
	te = itm.edge.fluid.te.value.array[0].scalar[0]

Instead, you can write::

	import itm.grid.cpo_tools as ct
	c = ct.Cpo(17151, 4, 'edge', 2.5, 'klingshi', 'aug', '4.09a')
	te=c.cpo.fluid.ne.value.array[0].scalar[0]

If the data in the UAL changes, you can reload the latest state by calling

    c.reload()


Accessing grids and data for CPOs using the general grid description
--------------------------------------------------------------------

The :class:`~itm.grid.cpo_tools.Cpo` class makes handling complex grids and data stored on them easy. ::

	c = ct.Cpo(17151, 4, 'edge', 2.5, 'klingshi', 'aug', '4.09a')
	c.grid

returns a itm.grid.base.Grid object wrapping the grid for the CPO, ::

	c.list_data()
	
returns a list of :class:`~itm.grid.data.ScalarData` objects for all fields in 
the CPO that are filled with data. Likewise, 

	c.list_data_lists()
	
returns a list of :class:'~itm.grid.data.ScalarDataList' objects for all arrays of
data fields that contain data. 

Detailed class documentation for :class:`itm.grid.cpo_tools.Cpo`
----------------------------------------------------------------

.. autoclass:: itm.grid.cpo_tools.Cpo
	:members:
	:undoc-members:	
	:special-members:

Handling sets of CPOs: CpoDescriptor 
====================================

The :class:`~itm.grid.cpo_tools.CpoDescriptor` 
class describes a set of CPOs, and can create the :class:`~itm.grid.cpo_tools.Cpo` objects for them.
 
Say you have a specific shot, for which different versions of the edge cpo were stored
with different run values. The following will give you a list of three :class:`~itm.grid.cpo_tools.Cpo` 
objects for the runs 2, 3 and 4: ::

  In [1]: import itm.grid.cpo_tools as ct

  In [2]: cd = ct.CpoDescriptor(17151, (2,3,4), 'edge', 2.5, 'klingshi', 'aug')

CpoDescriptor then behaves like a sequence of Cpo objects, and individual Cpo objects
can be accessed by their (zero-based, as usual in Python) index: ::

  In [3]: len(cd)
  Out[3]: 3

  In [10]: print cd[1]
  17151/3/2.5/edge

  In [4]: for c in cd:
     ...:     print str(c)
     ...:
  17151/2/2.5/edge
  17151/3/2.5/edge
  17151/4/2.5/edge

For every parameter to the CpoDescriptor you can give a list of values. For example, to get
the same CPO for different users: ::

  cd = ct.CpoDescriptor(17151, 'edge', 2.5, ('klingshi', 'coster'), 'aug')
  
Detailed class documentation for itm.grid.cpo_tools.CpoDescriptor
-----------------------------------------------------------------

.. autoclass:: itm.grid.cpo_tools.CpoDescriptor
	:members:
	:undoc-members:
	:special-members: