Write the model code

Code

Below is an example model which implements all the Decthings functions - createModelState, evaluate, train and getModelState.

Because the functions "evaluate" and "train" need access to the state, they are not exported directly but instead returned by the "instantiateModel" function. The instantiateModel function takes the state as a parameter, so this way the two functions have access to the state.

First, we import the file "decthings.ts". Then, we create the "createModelState" function, which will be called by Decthings when a new state should be created. Then, we create the "instantiateModel" function, which will be called by Decthings when the state data should be loaded. This function returns a class instance or object which contains the functions "evaluate", "train" and, optionally, "dispose". Lastly, we create a model by calling decthings.makeModel. Then, to make the model available to Decthings, we must set it as the default export. This is done with "export default ..".

Details about how the functions should be implemented is provided further down in this document.

The function "dispose" does not represent an operation, but rather that the functions train, evaluate and getModelState will no longer be called again, for this particular loaded state. This means that in the dispose function you should clear any used up resources associated with the loaded state. Since JavaScript is a garbage collected language, you can in many cases omit this function.

import * as decthings from './decthings'

async function createModelState(params: Map<string, decthings.DataLoader>, provider: decthings.StateProvider): Promise<void> {
    // Set the initial state to 0. Serialize it to binary data.
    let initialState = 0
    let serialized = Buffer.from(initialState.toString())
    provider.provide(serialized)
}

async function instantiateModel(stateLoader: decthings.StateLoader): Promise<decthings.Model> {
    // Load and deserialize the state from binary data.
    let state: Buffer[] = await stateLoader.next(1)
    let parsedState: number = Number(state[0].toString())
    return new ExampleModel(parsedState)
}

class ExampleModel implements decthings.Model {
    private state: number
    constructor(state: number) {
        this.state = state
    }

    async evaluate(params: Map<string, decthings.DataLoader>): Promise<{ name: string; values: decthings.Data | decthings.DataJson }[]> {
        // Get the input parameter "input"
        let inputLoader = params.get('input')

        // Process input into output
        let outputValues = new decthings.Data()
        while (inputLoader.hasNext()) {
            // Read input in batches of 10 elements
            let input = await inputLoader.next(10)

            // Process each input element
            for (let element of input.valuesElements()) {
                const inputNumber = element.getNumber()
                const outputNumber = inputNumber + this.state
                outputValues.push(decthings.DataElement.number(outputNumber))
            }
        }

        // Return the output
        return [{
            name: 'output',
            values: outputValues
        }]
    }

    async train(params: Map<string, decthings.DataLoader>, tracker: decthings.TrainTracker): Promise<void> {
        // Get the input parameter "increment"
        let incrementLoader = params.get('increment')
        let incrementData = await incrementLoader.next()
        let increment = incrementData.getElement(0).getNumber()

        for (let i = 1; i <= increment; i++) {
            // Simulate an expensive calculation by waiting 1 second
            await new Promise((resolve) => setTimeout(resolve, 1000))
            // Modify the state. Normally you would train by updating the weights and biases, but you know, this is a simple model.
            this.state++
            tracker.progress((i / increment) * 100)
            tracker.metrics([{ name: 'state', value: decthings.DataElement.f64(this.state) }])
        }
    }

    async getModelState(provider: decthings.StateProvider): Promise<void> {
        let serialized = Buffer.from(this.state.toString())
        provider.provide(serialized)
    }

    // Optional: Create the dispose function
    dispose(): void {
        return
    }
}

// Export default to make the model available to Decthings.
export default decthings.makeModel({
    createModelState,
    instantiateModel
})

Input data

The functions "createModelState", "evaluate" and "train" take input parameters that can be provided by whoever starts the operation. These are provided to the functions as the very first argument. The parameters are provided as a Map from string to decthings.DataLoader. The data loaders are used to read the input data. They allow you to read input in batches for efficient memory utilization.

The type decthings.DataLoader has the following methods:

• size ()

  Returns the total number of elements in the list.

• position ()

  Returns the position of the next element that will be read.

• setPosition (position)

  Set the current position.

• remaining ()

  Returns the number of remaining elements.

• hasNext (amount = 1)

  Return whether or not there are *amount* remaining elements.

• next (amount = 1)

  Reads *amount* elements. Returns a Promise which resolves to a decthings.Data containing the elements. Documentation for the decthings.Data class can be found here.

• shuffle ()

  Shuffles the data. Future calls to next will pick values from the shuffled data instead.

createModelState (parameters, provider)

The function "createModelState" takes a Map with keys of type string and values of type decthings.DataLoader as its first argument. The second argument will be a decthings.StateProvider, which is used to send the state data to Decthings. The function should not return anything, and the operation is considered complete when the function completes. You can also return a Promise (for example using the async keyword), in which case the operation will be considered complete when the promise resolves. In case of an error and you wish to cancel the operation, you should throw/reject an error. The details of the error will be forwarded to the user who started the operation.

The type decthings.StateProvider has just a single method:

• provide (data)

  Sends data to Decthings. *data* must be a Buffer or an array of Buffers. This function can be called multiple times, in case you do not have enough memory for all data at once. Each Buffer that is sent will be stored separately, so that when the "instantiateModel" function reads the state, they will receive the Buffers one at a time.

instantiateModel (stateloader)

The function "instantiateModel" takes a decthings.StateLoader as its only argument. The return type of the function must be an object or class instance which contains the keys/methods "evaluate", "train" and, optionally, "dispose".

The type decthings.StateLoader has the following methods:

• size ()

  Returns the total number of binary segments in the state.

• position ()

  Returns the position of the next element that will be read.

• setPosition (position)

  Set the current position.

• remaining ()

  Returns the number of remaining elements.

• hasNext (amount = 1)

  Return whether or not there are *amount* remaining elements.

• next (amount = 1)

  Reads *amount* elements. Returns a Promise which resolves to an array of Buffers.

• shuffle ()

  Shuffles the data. Future calls to next will pick values from the shuffled data instead.

For example, the following code loads all state segments:

async function instantiateModel(stateLoader: decthings.StateLoader): Promise<decthings.Model> {
    let allSegments: Buffer[] = await stateLoader.next(stateLoader.remaining())
    // Now create model which uses all segments
    ...
}

evaluate (parameters)

The function "evaluate" takes a Map with keys of type string and values of type decthings.DataLoader as its only argument. The return type of the function must be an array of objects with key "name", which is a string representing the parameter name, and "values" which is an instance of the class decthings.Data. You can also return a Promise (for example using the async keyword) which resolves to that. In case of an error and you wish to cancel the operation, you should throw/reject an error. The details of the error will be forwarded to the user who started the operation.

train (parameters, tracker)

The function "train" takes a Map with keys of type string and values of type decthings.DataLoader as its first argument. The second argument will be a decthings.TrainTracker, which can be used to report progress and metrics. The function should not return anything, and the operation is considered complete when the function completes. You can also return a Promise from your function (for example using the async keyword), in which case the operation will be considered complete when the promise resolves. In case of an error and you wish to cancel the operation, you should throw/reject an error. The details of the exception will be forwarded to the user who started the operation.

This function is optional. If it is not included, an error will be returned if you try to train the model.

The type decthings.TrainTracker has the following methods:

• progress (percentage)

  Reports progress. This value does not have any function, it is just as a display for the user who started the function. *percentage* should be a number between 0 and 100.

• metrics (data)

  Send metric data to Decthings. *data* should be an array of objects, where each object has a key "name" with value of type string, and a key "value" with value of type decthings.Data or decthings.DataElement. Documentation for the classes decthings.Data and decthings.DataElement can be found here.

• onCancel (callback)

  *callback* should be a function that takes no parameters. *callback* will be called when the training session has been cancelled. The training session can be cancelled for two reasons: 1. The user who started the training session has requested to cancel it. 2. The user who started the training session has requested that the training session should finish early. In this case, the function "getModelState" will be called after the training has been cancelled. In either case, cancelling is a signal that you should stop processing as soon as possible. If you don't, CPU, memory and disk will continue to be used for no reason.

createModelState (provider)

The function "getModelState" takes a decthings.StateProvider as its only argument. The state provider is used to send the state data to Decthings. The function should not return anything, and the operation is considered complete when the function completes. You can also return a Promise (for example using the async keyword), in which case the operation will be considered complete when the promise resolves. In case of an error and you wish to cancel the operation, you should throw/reject an error. The details of the error will be forwarded to the user who started the operation.

This function will be called after training to retrieve the new, updated state. Therefore, it can be omitted if the train function is omitted.

dispose ()

The function "dispose" does not represent an operation, but rather that the functions train, evaluate and getModelState will no longer be called again, for this particular loaded state. This means that in the dispose function you should clear any used up resources associated with the loaded state. Since JavaScript is a garbage collected language, you can in many cases omit this function.

This function is optional.