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
    Modifier and Type | Method and 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, 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`

Copyright © 2021 The Apache Software Foundation. All rights reserved.