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

All Methods Instance Methods Concrete Methods
`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, FrameBlock frame, boolean reuse)` Binds a frame object to a registered input variable.
`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` `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, ScalarObject scalar, boolean reuse)` Binds a scalar object 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.
`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 Detail

#### 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()

Overrides:
  `clone` in class `Object`