Package org.apache.sysds.api.jmlc

# Class PreparedScript

java.lang.Object
org.apache.sysds.api.jmlc.PreparedScript

All Implemented Interfaces:
  `ConfigurableAPI`

public class PreparedScript extends Object implements ConfigurableAPI
Representation of a prepared (precompiled) DML/PyDML script.

## Method Summary

Modifier and Type
Method
Description
`void`
`clearParameters()`
Remove all current values bound to input or output variables.
`void`
`clearPinnedData()`
Remove all references to pinned variables from this script.
`Object`
`clone()`
`PreparedScript`
`clone(boolean deep)`
Creates a cloned instance of the prepared script, which allows for concurrent execution without side effects.
`void`
`enableFunctionRecompile(String fnamespace, String... fnames)`
Enables function recompilation, selectively for the given functions.
`ResultVariables`
`executeScript()`
Executes the prepared script over the bound inputs, creating the result variables according to bound and registered outputs.
`String`
`explain()`
Explain the DML/PyDML program and view result as a string.
`CompilerConfig`
`getCompilerConfig()`
Get the compiler configuration object associated with the prepared script instance.
`DMLConfig`
`getDMLConfig()`
Get the dml configuration object associated with the prepared script instance.
`String`
`getLineageTrace(String var)`
Capture lineage of the DML/PyDML program and view result as a string.
`void`
`resetConfig()`
Reset configuration settings to default settings.
`void`
`setConfigProperty(String propertyName, String propertyValue)`
Set configuration property, such as `setConfigProperty("sysds.localtmpdir", "/tmp/systemds")`.
`void`
`setFrame(String varname, String[][] frame)`
Binds a frame object to a registered input variable.
`void`
`setFrame(String varname, String[][] frame, boolean reuse)`
Binds a frame object to a registered input variable.
`void`
`setFrame(String varname, String[][] frame, List<Types.ValueType> schema)`
Binds a frame object to a registered input variable.
`void`
`setFrame(String varname, String[][] frame, List<Types.ValueType> schema, boolean reuse)`
Binds a frame object to a registered input variable.
`void`
`setFrame(String varname, String[][] frame, List<Types.ValueType> schema, List<String> colnames)`
Binds a frame object to a registered input variable.
`void`
`setFrame(String varname, String[][] frame, List<Types.ValueType> schema, List<String> colnames, boolean reuse)`
Binds a frame object to a registered input variable.
`void`
`setFrame(String varname, FrameBlock frame, boolean reuse)`
Binds a frame object to a registered input variable.
`void`
`setMatrix(String varname, double[][] matrix)`
Binds a matrix object to a registered input variable.
`void`
`setMatrix(String varname, double[][] matrix, boolean reuse)`
Binds a matrix object to a registered input variable.
`void`
`setMatrix(String varname, MatrixBlock matrix, boolean reuse)`
Binds a matrix object to a registered input variable.
`void`
`setScalar(String varname, boolean scalar)`
Binds a scalar boolean to a registered input variable.
`void`
`setScalar(String varname, boolean scalar, boolean reuse)`
Binds a scalar boolean to a registered input variable.
`void`
`setScalar(String varname, double scalar)`
Binds a scalar double to a registered input variable.
`void`
`setScalar(String varname, double scalar, boolean reuse)`
Binds a scalar double to a registered input variable.
`void`
`setScalar(String varname, long scalar)`
Binds a scalar long to a registered input variable.
`void`
`setScalar(String varname, long scalar, boolean reuse)`
Binds a scalar long to a registered input variable.
`void`
`setScalar(String varname, String scalar)`
Binds a scalar string to a registered input variable.
`void`
`setScalar(String varname, String scalar, boolean reuse)`
Binds a scalar string to a registered input variable.
`void`
`setScalar(String varname, ScalarObject scalar, boolean reuse)`
Binds a scalar object to a registered input variable.
`String`
`statistics()`
Return a string containing runtime statistics.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Method Details

### resetConfig

public void resetConfig()
Description copied from interface: `ConfigurableAPI`
Reset configuration settings to default settings.

Specified by:
  `resetConfig` in interface `ConfigurableAPI`

### setConfigProperty

public void setConfigProperty(String propertyName, String propertyValue)
Description copied from interface: `ConfigurableAPI`
Set configuration property, such as `setConfigProperty("sysds.localtmpdir", "/tmp/systemds")`.

Specified by:
  `setConfigProperty` in interface `ConfigurableAPI`
Parameters:
  `propertyName` - property name
  `propertyValue` - property value

### getDMLConfig

public DMLConfig getDMLConfig()
Get the dml configuration object associated with the prepared script instance.

Returns:
  dml configuration

### getCompilerConfig

public CompilerConfig getCompilerConfig()
Get the compiler configuration object associated with the prepared script instance.

Returns:
  compiler configuration

### setScalar

public void setScalar(String varname, boolean scalar)
Binds a scalar boolean to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - boolean value

### setScalar

public void setScalar(String varname, boolean scalar, boolean reuse)
Binds a scalar boolean to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - boolean value
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setScalar

public void setScalar(String varname, long scalar)
Binds a scalar long to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - long value

### setScalar

public void setScalar(String varname, long scalar, boolean reuse)
Binds a scalar long to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - long value
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setScalar

public void setScalar(String varname, double scalar)
Binds a scalar double to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - double value

### setScalar

public void setScalar(String varname, double scalar, boolean reuse)
Binds a scalar double to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - double value
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setScalar

public void setScalar(String varname, String scalar)
Binds a scalar string to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - string value

### setScalar

public void setScalar(String varname, String scalar, boolean reuse)
Binds a scalar string to a registered input variable.

Parameters:
  `varname` - input variable name
  `scalar` - string value
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setScalar

public void setScalar(String varname, ScalarObject scalar, boolean reuse)
Binds a scalar object to a registered input variable. If reuse requested, then the input is guaranteed to be preserved over multiple `executeScript` calls.

Parameters:
  `varname` - input variable name
  `scalar` - scalar object
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setMatrix

public void setMatrix(String varname, double[][] matrix)
Binds a matrix object to a registered input variable.

Parameters:
  `varname` - input variable name
  `matrix` - two-dimensional double array matrix representation

### setMatrix

public void setMatrix(String varname, double[][] matrix, boolean reuse)
Binds a matrix object to a registered input variable.

Parameters:
  `varname` - input variable name
  `matrix` - two-dimensional double array matrix representation
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setMatrix

public void setMatrix(String varname, MatrixBlock matrix, boolean reuse)
Binds a matrix object to a registered input variable. If reuse requested, then the input is guaranteed to be preserved over multiple `executeScript` calls.

Parameters:
  `varname` - input variable name
  `matrix` - matrix represented as a MatrixBlock
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setFrame

public void setFrame(String varname, String[][] frame)
Binds a frame object to a registered input variable.

Parameters:
  `varname` - input variable name
  `frame` - two-dimensional string array frame representation

### setFrame

public void setFrame(String varname, String[][] frame, List<Types.ValueType> schema)
Binds a frame object to a registered input variable.

Parameters:
  `varname` - input variable name
  `frame` - two-dimensional string array frame representation
  `schema` - list representing the types of the frame columns

### setFrame

public void setFrame(String varname, String[][] frame, List<Types.ValueType> schema, List<String> colnames)
Binds a frame object to a registered input variable.

Parameters:
  `varname` - input variable name
  `frame` - two-dimensional string array frame representation
  `schema` - list representing the types of the frame columns
  `colnames` - frame column names

### setFrame

public void setFrame(String varname, String[][] frame, boolean reuse)
Binds a frame object to a registered input variable.

Parameters:
  `varname` - input variable name
  `frame` - two-dimensional string array frame representation
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setFrame

public void setFrame(String varname, String[][] frame, List<Types.ValueType> schema, boolean reuse)
Binds a frame object to a registered input variable.

Parameters:
  `varname` - input variable name
  `frame` - two-dimensional string array frame representation
  `schema` - list representing the types of the frame columns
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setFrame

public void setFrame(String varname, String[][] frame, List<Types.ValueType> schema, List<String> colnames, boolean reuse)
Binds a frame object to a registered input variable.

Parameters:
  `varname` - input variable name
  `frame` - two-dimensional string array frame representation
  `schema` - list representing the types of the frame columns
  `colnames` - frame column names
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### setFrame

public void setFrame(String varname, FrameBlock frame, boolean reuse)
Binds a frame object to a registered input variable. If reuse requested, then the input is guaranteed to be preserved over multiple `executeScript` calls.

Parameters:
  `varname` - input variable name
  `frame` - frame represented as a FrameBlock
  `reuse` - if `true`, preserve value over multiple `executeScript` calls

### clearParameters

public void clearParameters()
Remove all current values bound to input or output variables.

### clearPinnedData

public void clearPinnedData()
Remove all references to pinned variables from this script. Note: this *does not* remove the underlying data. It merely removes a reference to it from this prepared script. This is useful if you want to maintain an independent cache of weights and allow the JVM to garbage collect under memory pressure.

### executeScript

public ResultVariables executeScript()
Executes the prepared script over the bound inputs, creating the result variables according to bound and registered outputs.

Returns:
  ResultVariables object encapsulating output results

### explain

public String explain()
Explain the DML/PyDML program and view result as a string.

Returns:
  string results of explain

### getLineageTrace

public String getLineageTrace(String var)
Capture lineage of the DML/PyDML program and view result as a string.

Parameters:
  `var` - the output variable name on which lineage trace is sought
Returns:
  string results of lineage trace

### statistics

public String statistics()
Return a string containing runtime statistics. Note: these are not thread local and will reflect execution in all threads

Returns:
  string containing statistics

### enableFunctionRecompile

public void enableFunctionRecompile(String fnamespace, String... fnames)
Enables function recompilation, selectively for the given functions. If dynamic recompilation is globally enabled this has no additional effect; otherwise the given functions are dynamically recompiled once on every entry but not at the granularity of individually last-level program blocks. Use this fine-grained recompilation option for important functions in small-data scenarios where dynamic recompilation overheads might not be amortized.

Parameters:
  `fnamespace` - function namespace, null for default namespace
  `fnames` - function name

### clone

public PreparedScript clone(boolean deep)
Creates a cloned instance of the prepared script, which allows for concurrent execution without side effects.

Parameters:
  `deep` - indicator if a deep copy needs to be created; if false, only a shallow (i.e., by reference) copy of the program and read-only meta data is created.
Returns:
  an equivalent prepared script

### clone

public Object clone()