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