ResInsight/OctavePlugin/ResInsightOctaveInterfaceSpecification.txt

Considerations
==================================

This function interface towards ResInsight is currently a Draft, 
and not addressing some issues. The known issues are :

1. How do we address Cases in the future when we have Case Groups ?
   Where do we write/store the generated data ?
2. Users wants to run octave operations on several cases/groups.
   There are two ways (at least) of doing that. Either from ResInsight:
		1 Command to call a specified Octave Script for each selected Case 
		2 Creating Scripts that loops over all selections in ResInsight
	Option 2 is needed if users wants to do cross-case operations 
	Option 1 seems intuitive for one case operations
	How does these two relate ?

3. Do we need functions to retreive the selected/active cases/groups ?
4. Do we need functions to retreive info on what Parent cells an LGR occupies ?


Project Information
==================================

Vector[Casenames] riGetCaseNames()
 
	Returns a vector of all the case names in the current ResInsight project
	Use this to determine the number of cases as well
	
	This probably needs some additions related to Case Groups


Retreiving Grid Metadata
==================================

Matrix[ActiveCells][8] riGetActiveCellInfo( [CaseName/CaseIndex])

	Returns a two dimensional matrix: [ActiveCells][8]

	Containing grid and ijk information about the cells from the Eclipse Case defined.
	The columns contain the following information:
		1: GridIndex: The index of the grid the cell resides in. (Main grid has index 0) 
		2, 3, 4: I, J, K: 1-based index address of the cell in the grid.
		5: ParentGridIndex. The index to the grid that this cell's grid is residing in.
		6, 7, 8: PI, PJ, PK address of the parent grid cell that this cell is a part of.
	If the Eclipse Case is not defined, the active View in ResInsight is used.	   



Matrix[g0I, g0J, g0K; ... ; gnI, gnJ, gnK] riGetGridDimensions ( [CaseName/CaseIndex]) 

	Returns a matrix: [NuberOfGrids][3] 
	containing the I, J, K dimensions of the main grid and all the LGR's
	
# Unnecessary ? # Vector(3)[ICount, JCount, KCount] riGetMainGridDimensions( [CaseName/CaseIndex])
# Unnecessary ? # 
# Unnecessary ? # 	Returns a vector of size 3: [ICount, JCount, KCount] 
# Unnecessary ? # 	Containing the dimensions of the main grid in the requested case.
# Unnecessary ? # 	If the Eclipse Case is not defined, the active View in ResInsight is used."
# Unnecessary ? # 
# Unnecessary ? # NumberOfGrids riGetNumLGRs([Casename/CaseIndex])
# Unnecessary ? # 
# Unnecessary ? # 	Returns an integer telling the number of LGRS in this case 



Vector[Dates] riGetTimestepDates([Casename/CaseIndex])

	Returns a vector of all the timesteps in a case as dates YYYY.MM.DD 


Vector[Days] riGetTimestepDays([Casename/CaseIndex])

	Returns a vector of all the timesteps in a case as days from start


Retreiving property data
==================================

Matrix[ActiveCells][Timesteps] riGetActiveCellProperty( [CaseName/CaseIndex], PropertyName )

	Returns a two dimentional matrix: [ActiveCells][Timesteps]

	Containing the requested property data from the Eclipse Case defined.
	If the Eclipse Case is not defined, the active View in ResInsight is used.		


Matrix[numI][numJ][numK][timeSteps] riGetGridProperty( [Casename/CaseIndex], GridIndex , PropertyName )
Matrix[numI][numJ][numK]            riGetGridProperty( [Casename/CaseIndex], GridIndex , PropertyName, TimeStep )

	Returns a 4D or 3D matrix of the requested property data for all the gridcells in the requested grid.
	Grids are indexed from 0 - main grid to Max num LGR's 
	
Writing Back to ResInsight
==================================

riSetActiveCellProperty( Matrix(nActiveCells, nTimesteps), [CaseName/CaseIndex], PropertyName )

	Interprets the supplied matrix as an eclipse property set, and puts the data into
	ResInsight as a "Generated" property with the name "PropertyName". The property
	is added to the active case if no case specification is given, or to the Eclipse Case
	named "CaseName" or to the case number "CaseIndex". "


riSetGridProperty( Matrix[numI][numJ][numK][timeSteps] , [CaseName/CaseIndex], GridIndex, PropertyName )
riSetGridProperty( Matrix[numI][numJ][numK], 			 [CaseName/CaseIndex], GridIndex, PropertyName , TimeStep)
	
	Interprets the supplied matrix as an eclipse property set defined for all cells in one of the grids in a case,
	and puts the data into ResInsight as a "Generated" property with the name "PropertyName". The property
	is added to the active case if no case specification is given, or to the Eclipse Case
	named "CaseName" or to the case number "CaseIndex". "

Cell geometry functions:
=================================

Matrix[numI*Vector(3)][numJ*Vec(3)] [numK*Vec(3)] riGetCellCenters( [Casename/CaseIndex], GridIndex )

	Returns the UTM coordinates (X, Y, Z) for centerpoint of all cells


Matrix[numI*8*Vector(3)][numJ*8*Vec(3)] [numK*8*Vec(3)] riGetCellCorners( [Casename/CaseIndex], GridIndex )

	Returns the UTM coordinates of the each cells 8 corners


Well data functions
=================================
Vector[WellNames] riGetWellNames([Casename/CaseIndex])

	Returns the names of all the wells in the case

Vector[ I, J, K, GridNr] riGetWellCells([Casename/CaseIndex], WellName/WellIndex, TimeStep, Producing/Injecting/Any)

	Returns the cells that has the requested production status for the given well and timestep

	
Comments to remember/consider
=================================
<EFBFBD>Execute for all cases within group<75> in script-tree

Well trajectories (alternative trajectory like Planned / Drilled /Real Time/ Project ahead?)
riGetTrajectories(well, case) ? MD, Inc, Az, Norht(X), East(Y), TVD(Z),DLS,BUR,TR,prop/log/connections?

Operator to restrict operation to be carried out inside a given polygon object
riInside(polygon)

Set Octave function Case ID as a function parameter (enable for loops)
Write grid data to file on .grdecl format (and read & append?)