objc2_ml_compute/generated/

MLCTrainingGraph.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
use objc2_foundation::*;

use crate::*;

extern_class!(
    /// A training graph created from one or more MLCGraph objects
    /// plus additional layers added directly to the training graph.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/mlcompute/mlctraininggraph?language=objc)
    #[unsafe(super(MLCGraph, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    #[cfg(feature = "MLCGraph")]
    #[deprecated]
    pub struct MLCTrainingGraph;
);

#[cfg(feature = "MLCGraph")]
extern_conformance!(
    unsafe impl NSObjectProtocol for MLCTrainingGraph {}
);

#[cfg(feature = "MLCGraph")]
impl MLCTrainingGraph {
    extern_methods!(
        #[cfg(feature = "MLCOptimizer")]
        /// The optimizer to be used with the training graph
        #[deprecated]
        #[unsafe(method(optimizer))]
        #[unsafe(method_family = none)]
        pub unsafe fn optimizer(&self) -> Option<Retained<MLCOptimizer>>;

        /// Returns the total size in bytes of device memory used for all intermediate tensors
        /// for forward, gradient passes and optimizer update for all layers in the training graph.
        /// We recommend executing an iteration before checking the device memory size as
        /// the buffers needed get allocated when the corresponding pass such as gradient,
        /// optimizer update is executed.
        ///
        /// Returns: A NSUInteger value
        #[deprecated]
        #[unsafe(method(deviceMemorySize))]
        #[unsafe(method_family = none)]
        pub unsafe fn deviceMemorySize(&self) -> NSUInteger;

        #[cfg(all(feature = "MLCLayer", feature = "MLCOptimizer"))]
        /// Create a training graph
        ///
        /// Parameter `graphObjects`: The layers from these graph objects will be added to the training graph
        ///
        /// Parameter `lossLayer`: The loss layer to use.  The loss layer can also be added to the training graph
        /// using nodeWithLayer:sources:lossLabels
        ///
        /// Parameter `optimizer`: The optimizer to use
        ///
        /// Returns: A new training graph object
        #[deprecated]
        #[unsafe(method(graphWithGraphObjects:lossLayer:optimizer:))]
        #[unsafe(method_family = none)]
        pub unsafe fn graphWithGraphObjects_lossLayer_optimizer(
            graph_objects: &NSArray<MLCGraph>,
            loss_layer: Option<&MLCLayer>,
            optimizer: Option<&MLCOptimizer>,
        ) -> Retained<Self>;

        #[cfg(feature = "MLCTensor")]
        /// Add the list of inputs to the training graph
        ///
        /// Parameter `inputs`: The inputs
        ///
        /// Parameter `lossLabels`: The loss label inputs
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(addInputs:lossLabels:))]
        #[unsafe(method_family = none)]
        pub unsafe fn addInputs_lossLabels(
            &self,
            inputs: &NSDictionary<NSString, MLCTensor>,
            loss_labels: Option<&NSDictionary<NSString, MLCTensor>>,
        ) -> bool;

        #[cfg(feature = "MLCTensor")]
        /// Add the list of inputs to the training graph
        ///
        /// Each input, loss label or label weights tensor is identified by a NSString.
        /// When the training graph is executed, this NSString is used to identify which data object
        /// should be as input data for each tensor whose device memory needs to be updated
        /// before the graph is executed.
        ///
        /// Parameter `inputs`: The inputs
        ///
        /// Parameter `lossLabels`: The loss label inputs
        ///
        /// Parameter `lossLabelWeights`: The loss label weights
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(addInputs:lossLabels:lossLabelWeights:))]
        #[unsafe(method_family = none)]
        pub unsafe fn addInputs_lossLabels_lossLabelWeights(
            &self,
            inputs: &NSDictionary<NSString, MLCTensor>,
            loss_labels: Option<&NSDictionary<NSString, MLCTensor>>,
            loss_label_weights: Option<&NSDictionary<NSString, MLCTensor>>,
        ) -> bool;

        #[cfg(feature = "MLCTensor")]
        /// Add the list of outputs to the training graph
        ///
        /// Parameter `outputs`: The outputs
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(addOutputs:))]
        #[unsafe(method_family = none)]
        pub unsafe fn addOutputs(&self, outputs: &NSDictionary<NSString, MLCTensor>) -> bool;

        #[cfg(feature = "MLCTensor")]
        /// Add the list of tensors whose contributions are not to be taken when computing gradients during gradient pass
        ///
        /// Parameter `tensors`: The list of tensors
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(stopGradientForTensors:))]
        #[unsafe(method_family = none)]
        pub unsafe fn stopGradientForTensors(&self, tensors: &NSArray<MLCTensor>) -> bool;

        #[cfg(all(feature = "MLCDevice", feature = "MLCTypes"))]
        /// Compile the training graph for a device.
        ///
        /// Parameter `options`: The compiler options to use when compiling the training graph
        ///
        /// Parameter `device`: The MLCDevice object
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(compileWithOptions:device:))]
        #[unsafe(method_family = none)]
        pub unsafe fn compileWithOptions_device(
            &self,
            options: MLCGraphCompilationOptions,
            device: &MLCDevice,
        ) -> bool;

        #[cfg(all(
            feature = "MLCDevice",
            feature = "MLCTensor",
            feature = "MLCTensorData",
            feature = "MLCTypes"
        ))]
        /// Compile the training graph for a device.
        ///
        /// Specifying the list of constant tensors when we compile the graph allows MLCompute to perform additional optimizations at compile time.
        ///
        /// Parameter `options`: The compiler options to use when compiling the training graph
        ///
        /// Parameter `device`: The MLCDevice object
        ///
        /// Parameter `inputTensors`: The list of input tensors that are constants
        ///
        /// Parameter `inputTensorsData`: The tensor data to be used with these constant input tensors
        ///
        /// Returns: A boolean indicating success or failure
        #[unsafe(method(compileWithOptions:device:inputTensors:inputTensorsData:))]
        #[unsafe(method_family = none)]
        pub unsafe fn compileWithOptions_device_inputTensors_inputTensorsData(
            &self,
            options: MLCGraphCompilationOptions,
            device: &MLCDevice,
            input_tensors: Option<&NSDictionary<NSString, MLCTensor>>,
            input_tensors_data: Option<&NSDictionary<NSString, MLCTensorData>>,
        ) -> bool;

        #[cfg(feature = "MLCOptimizer")]
        /// Compile the optimizer to be used with a training graph.
        ///
        /// Typically the optimizer to be used with a training graph is specifed when the training graph is created using
        /// graphWithGraphObjects:lossLayer:optimizer.  The optimizer will be compiled in when compileWithOptions:device
        /// is called if an optimizer is specified with the training graph.  In the case where the optimizer to be used is not known
        /// when the graph is created or compiled, this method can be used to associate and compile a training graph with an optimizer.
        ///
        /// Parameter `optimizer`: The MLCOptimizer object
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(compileOptimizer:))]
        #[unsafe(method_family = none)]
        pub unsafe fn compileOptimizer(&self, optimizer: &MLCOptimizer) -> bool;

        /// Link mutiple training graphs
        ///
        /// This is used to link subsequent training graphs with first training sub-graph.
        /// This method should be used when we have tensors shared by one or more layers in multiple sub-graphs
        ///
        /// Parameter `graphs`: The list of training graphs to link
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(linkWithGraphs:))]
        #[unsafe(method_family = none)]
        pub unsafe fn linkWithGraphs(&self, graphs: &NSArray<MLCTrainingGraph>) -> bool;

        #[cfg(feature = "MLCTensor")]
        /// Get the gradient tensor for an input tensor
        ///
        /// Parameter `input`: The input tensor
        ///
        /// Returns: The gradient tensor
        #[deprecated]
        #[unsafe(method(gradientTensorForInput:))]
        #[unsafe(method_family = none)]
        pub unsafe fn gradientTensorForInput(
            &self,
            input: &MLCTensor,
        ) -> Option<Retained<MLCTensor>>;

        #[cfg(all(feature = "MLCLayer", feature = "MLCTensor"))]
        /// Get the source gradient tensors for a layer in the training graph
        ///
        /// Parameter `layer`: A layer in the training graph
        ///
        /// Returns: A list of tensors
        #[deprecated]
        #[unsafe(method(sourceGradientTensorsForLayer:))]
        #[unsafe(method_family = none)]
        pub unsafe fn sourceGradientTensorsForLayer(
            &self,
            layer: &MLCLayer,
        ) -> Retained<NSArray<MLCTensor>>;

        #[cfg(all(feature = "MLCLayer", feature = "MLCTensor"))]
        /// Get the result gradient tensors for a layer in the training graph
        ///
        /// Parameter `layer`: A layer in the training graph
        ///
        /// Returns: A list of tensors
        #[deprecated]
        #[unsafe(method(resultGradientTensorsForLayer:))]
        #[unsafe(method_family = none)]
        pub unsafe fn resultGradientTensorsForLayer(
            &self,
            layer: &MLCLayer,
        ) -> Retained<NSArray<MLCTensor>>;

        #[cfg(all(feature = "MLCLayer", feature = "MLCTensor"))]
        /// Get the gradient data for a trainable parameter associated with a layer
        ///
        /// This can be used to get the gradient data for weights or biases parameters associated with a convolution,
        /// fully connected or convolution transpose layer
        ///
        /// Parameter `parameter`: The updatable parameter associated with the layer
        ///
        /// Parameter `layer`: A layer in the training graph.  Must be one of the following:
        /// - MLCConvolutionLayer
        /// - MLCFullyConnectedLayer
        /// - MLCBatchNormalizationLayer
        /// - MLCInstanceNormalizationLayer
        /// - MLCGroupNormalizationLayer
        /// - MLCLayerNormalizationLayer
        /// - MLCEmbeddingLayer
        /// - MLCMultiheadAttentionLayer
        ///
        /// Returns: The gradient data.  Will return nil if the layer is marked as not trainable or if
        /// training graph is not executed with separate calls to forward and gradient passes.
        #[deprecated]
        #[unsafe(method(gradientDataForParameter:layer:))]
        #[unsafe(method_family = none)]
        pub unsafe fn gradientDataForParameter_layer(
            &self,
            parameter: &MLCTensor,
            layer: &MLCLayer,
        ) -> Option<Retained<NSData>>;

        #[cfg(feature = "MLCTensor")]
        /// Allocate an entry for a user specified gradient for a tensor
        ///
        /// Parameter `tensor`: A result tensor produced by a layer in the training graph
        /// that is input to some user specified code and will need to
        /// provide a user gradient during the gradient pass.
        ///
        /// Returns: A gradient tensor
        #[deprecated]
        #[unsafe(method(allocateUserGradientForTensor:))]
        #[unsafe(method_family = none)]
        pub unsafe fn allocateUserGradientForTensor(
            &self,
            tensor: &MLCTensor,
        ) -> Option<Retained<MLCTensor>>;

        #[cfg(all(
            feature = "MLCTensor",
            feature = "MLCTensorData",
            feature = "MLCTypes",
            feature = "block2"
        ))]
        /// Execute the training graph (forward, gradient and optimizer update) with given source and label data
        ///
        /// Execute the training graph with given source and label data.  If an optimizer is specified, the optimizer update is applied.
        /// If MLCExecutionOptionsSynchronous is specified in 'options', this method returns after the graph has been executed.
        /// Otherwise, this method returns after the graph has been queued for execution. The completion handler is called after the graph
        /// has finished execution.
        ///
        /// Parameter `inputsData`: The data objects to use for inputs
        ///
        /// Parameter `lossLabelsData`: The data objects to use for loss labels
        ///
        /// Parameter `lossLabelWeightsData`: The data objects to use for loss label weights
        ///
        /// Parameter `batchSize`: The batch size to use.  For a graph where batch size changes between layers this value must be 0.
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeWithInputsData:lossLabelsData:lossLabelWeightsData:batchSize:options:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeWithInputsData_lossLabelsData_lossLabelWeightsData_batchSize_options_completionHandler(
            &self,
            inputs_data: &NSDictionary<NSString, MLCTensorData>,
            loss_labels_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            loss_label_weights_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            batch_size: NSUInteger,
            options: MLCExecutionOptions,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        #[cfg(all(
            feature = "MLCTensor",
            feature = "MLCTensorData",
            feature = "MLCTypes",
            feature = "block2"
        ))]
        /// Execute the training graph (forward, gradient and optimizer update) with given source and label data
        ///
        /// Parameter `inputsData`: The data objects to use for inputs
        ///
        /// Parameter `lossLabelsData`: The data objects to use for loss labels
        ///
        /// Parameter `lossLabelWeightsData`: The data objects to use for loss label weights
        ///
        /// Parameter `outputsData`: The data objects to use for outputs
        ///
        /// Parameter `batchSize`: The batch size to use.  For a graph where batch size changes between layers this value must be 0.
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeWithInputsData:lossLabelsData:lossLabelWeightsData:outputsData:batchSize:options:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeWithInputsData_lossLabelsData_lossLabelWeightsData_outputsData_batchSize_options_completionHandler(
            &self,
            inputs_data: &NSDictionary<NSString, MLCTensorData>,
            loss_labels_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            loss_label_weights_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            outputs_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            batch_size: NSUInteger,
            options: MLCExecutionOptions,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        #[cfg(all(feature = "MLCTensor", feature = "MLCTypes", feature = "block2"))]
        /// Execute the forward pass of the training graph
        ///
        /// Parameter `batchSize`: The batch size to use.  For a graph where batch size changes between layers this value must be 0.
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeForwardWithBatchSize:options:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeForwardWithBatchSize_options_completionHandler(
            &self,
            batch_size: NSUInteger,
            options: MLCExecutionOptions,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        #[cfg(all(
            feature = "MLCTensor",
            feature = "MLCTensorData",
            feature = "MLCTypes",
            feature = "block2"
        ))]
        /// Execute the forward pass for the training graph
        ///
        /// Parameter `batchSize`: The batch size to use.  For a graph where batch size changes between layers this value must be 0.
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `outputsData`: The data objects to use for outputs
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeForwardWithBatchSize:options:outputsData:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeForwardWithBatchSize_options_outputsData_completionHandler(
            &self,
            batch_size: NSUInteger,
            options: MLCExecutionOptions,
            outputs_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        #[cfg(all(feature = "MLCTensor", feature = "MLCTypes", feature = "block2"))]
        /// Execute the gradient pass of the training graph
        ///
        /// Parameter `batchSize`: The batch size to use.  For a graph where batch size changes between layers this value must be 0.
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeGradientWithBatchSize:options:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeGradientWithBatchSize_options_completionHandler(
            &self,
            batch_size: NSUInteger,
            options: MLCExecutionOptions,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        #[cfg(all(
            feature = "MLCTensor",
            feature = "MLCTensorData",
            feature = "MLCTypes",
            feature = "block2"
        ))]
        /// Execute the gradient pass of the training graph
        ///
        /// Parameter `batchSize`: The batch size to use.  For a graph where batch size changes between layers this value must be 0.
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `outputsData`: The data objects to use for outputs
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeGradientWithBatchSize:options:outputsData:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeGradientWithBatchSize_options_outputsData_completionHandler(
            &self,
            batch_size: NSUInteger,
            options: MLCExecutionOptions,
            outputs_data: Option<&NSDictionary<NSString, MLCTensorData>>,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        #[cfg(all(feature = "MLCTensor", feature = "MLCTypes", feature = "block2"))]
        /// Execute the optimizer update pass of the training graph
        ///
        /// Parameter `options`: The execution options
        ///
        /// Parameter `completionHandler`: The completion handler
        ///
        /// Returns: A boolean indicating success or failure
        ///
        /// # Safety
        ///
        /// `completion_handler` must be a valid pointer or null.
        #[deprecated]
        #[unsafe(method(executeOptimizerUpdateWithOptions:completionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn executeOptimizerUpdateWithOptions_completionHandler(
            &self,
            options: MLCExecutionOptions,
            completion_handler: MLCGraphCompletionHandler,
        ) -> bool;

        /// Synchronize updates (weights/biases from convolution, fully connected and LSTM layers, tensor parameters)
        /// from device memory to host memory.
        #[deprecated]
        #[unsafe(method(synchronizeUpdates))]
        #[unsafe(method_family = none)]
        pub unsafe fn synchronizeUpdates(&self);

        #[cfg(feature = "MLCTensorParameter")]
        /// Set the input tensor parameters that also will be updated by the optimizer
        ///
        /// These represent the list of input tensors to be updated when we execute the optimizer update
        /// Weights, bias or beta, gamma tensors are not included in this list.  MLCompute automatically
        /// adds them to the parameter list based on whether the layer is marked as updatable or not.
        ///
        /// Parameter `parameters`: The list of input tensors to be updated by the optimizer
        ///
        /// Returns: A boolean indicating success or failure
        #[deprecated]
        #[unsafe(method(setTrainingTensorParameters:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setTrainingTensorParameters(
            &self,
            parameters: &NSArray<MLCTensorParameter>,
        ) -> bool;

        #[cfg(all(
            feature = "MLCTensor",
            feature = "MLCTensorData",
            feature = "MLCTensorOptimizerDeviceData"
        ))]
        /// Associates the given optimizer data and device data buffers with the tensor.
        /// Returns true if the data is successfully associated with the tensor and copied to the device.
        ///
        /// The caller must guarantee the lifetime of the underlying memory of
        /// `data`for the entirety of the tensor's
        /// lifetime.  The
        /// `deviceData`buffers are allocated by MLCompute.  This method must be called
        /// before executeOptimizerUpdateWithOptions or executeWithInputsData is called for the training graph.
        /// We recommend using this method instead of using [MLCTensor bindOptimizerData] especially if the
        /// optimizer update is being called multiple times for each batch.
        ///
        /// Parameter `data`: The optimizer data to be associated with the tensor
        ///
        /// Parameter `deviceData`: The optimizer device data to be associated with the tensor
        ///
        /// Parameter `tensor`: The tensor
        ///
        /// Returns: A Boolean value indicating whether the data is successfully associated with the tensor .
        #[deprecated]
        #[unsafe(method(bindOptimizerData:deviceData:withTensor:))]
        #[unsafe(method_family = none)]
        pub unsafe fn bindOptimizerData_deviceData_withTensor(
            &self,
            data: &NSArray<MLCTensorData>,
            device_data: Option<&NSArray<MLCTensorOptimizerDeviceData>>,
            tensor: &MLCTensor,
        ) -> bool;
    );
}

/// Methods declared on superclass `MLCGraph`.
#[cfg(feature = "MLCGraph")]
impl MLCTrainingGraph {
    extern_methods!(
        /// Creates a new graph.
        ///
        /// Returns: A new graph.
        #[deprecated]
        #[unsafe(method(graph))]
        #[unsafe(method_family = none)]
        pub unsafe fn graph() -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
#[cfg(feature = "MLCGraph")]
impl MLCTrainingGraph {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}