UNPKG

8.02 kBTypeScriptView Raw
1/**
2 * @license
3 * Copyright 2018 Google LLC
4 *
5 * Use of this source code is governed by an MIT-style
6 * license that can be found in the LICENSE file or at
7 * https://opensource.org/licenses/MIT.
8 * =============================================================================
9 */
10/// <amd-module name="@tensorflow/tfjs-layers/dist/variables" />
11import * as tfc from '@tensorflow/tfjs-core';
12import { DataType, Tensor } from '@tensorflow/tfjs-core';
13import { Constraint } from './constraints';
14import { Shape } from './keras_format/common';
15/**
16 * A `tf.layers.LayerVariable` is similar to a `tf.Tensor` in that it has a
17 * dtype and shape, but its value is mutable. The value is itself represented
18 * as a`tf.Tensor`, and can be read with the `read()` method and updated with
19 * the `write()` method.
20 */
21export declare class LayerVariable {
22 readonly dtype: DataType;
23 readonly shape: Shape;
24 readonly id: number;
25 readonly name: string;
26 readonly originalName: string;
27 private trainable_;
28 protected readonly val: tfc.Variable;
29 readonly constraint: Constraint;
30 /**
31 * Construct Variable from a `tf.Tensor`.
32 *
33 * If not explicitly named, the Variable will be given a name with the
34 * prefix 'Variable'. Variable names are unique. In the case of name
35 * collision, suffixies '_<num>' will be added to the name.
36 *
37 * @param val Initial value of the Variable.
38 * @param name Name of the variable. If `null` or `undefined` is provided, it
39 * will default a name with the prefix 'Variable'.
40 * @param constraint Optional, projection function to be applied to the
41 * variable after optimize updates
42 * @throws ValueError if `name` is `null` or `undefined`.
43 */
44 constructor(val: Tensor, dtype?: DataType, name?: string, trainable?: boolean, constraint?: Constraint);
45 /**
46 * Get a snapshot of the Variable's value.
47 *
48 * The returned value is a snapshot of the Variable's value at the time of
49 * the invocation. Future mutations in the value of the tensor will only
50 * be reflected by future calls to this method.
51 */
52 read(): Tensor;
53 /**
54 * Update the value of the Variable.
55 *
56 * @param newVal: The new value to update to. Must be consistent with the
57 * dtype and shape of the Variable.
58 * @return This Variable.
59 */
60 write(newVal: Tensor): this;
61 /**
62 * Dispose this LayersVariable instance from memory.
63 */
64 dispose(): void;
65 protected assertNotDisposed(): void;
66 get trainable(): boolean;
67 set trainable(trainable: boolean);
68}
69/**
70 * Create a Variable.
71 * @param x The initial value of the `Variable`.
72 * @param dtype optional, the type of the variable.
73 * @param name optional, the name of the variable, default provided by
74 * Variable.
75 * @param constraint optional, a constraint to be applied after every update.
76 * @return The newly instantiated `Variable`.
77 */
78export declare function variable(x: Tensor, dtype?: DataType, name?: string, constraint?: Constraint): LayerVariable;
79/**
80 * Instantiates an all-zeros Variable and returns it.
81 *
82 * @param shape Shape of the tensor.
83 * @param dtype DType of the tensor.
84 * @param name Name of the tensor.
85 * @return An all-zero Variable.
86 */
87export declare function zerosVariable(shape: Shape, dtype?: DataType, name?: string): LayerVariable;
88/**
89 * Instantiates an all-zeros tensor of the same shape as another tensor.
90 *
91 * @param x The other tensor.
92 * @param dtype DType of the tensor.
93 * @param name Name of the tensor.
94 * @return A newly instantiated Variable.
95 */
96export declare function zerosLike(x: Tensor, dtype?: DataType, name?: string): LayerVariable;
97/**
98 * Instantiates an all-ones tensor and returns it.
99 *
100 * @param shape Shape of the tensor.
101 * @param dtype DType of the tensor.
102 * @param name Name of the tensor.
103 * @return An all-ones Variable.
104 */
105export declare function onesVariable(shape: Shape, dtype?: DataType, name?: string): LayerVariable;
106/**
107 * Instantiates an all-ones tensor of the same shape as another tensor.
108 *
109 * @param x The other tensor.
110 * @param dtype DType of the tensor.
111 * @param name Name of the tensor.
112 * @return A newly instantiated Variable.
113 */
114export declare function onesLike(x: Tensor, dtype?: DataType, name?: string): LayerVariable;
115/**
116 * Instantiate an identity matrix and returns it, as a Variable
117 *
118 * @param size Number of rows/columns.
119 * @param dtype Data type of returned Variable.
120 * @param name Name of returned Variable.
121 * @return A Variable, an identity matrix.
122 */
123export declare function eyeVariable(size: number, dtype?: DataType, name?: string): LayerVariable;
124/**
125 * Get a Variable with uniform distribution of values.
126 * @param shape Shape of the tensor.
127 * @param minval Lower bound of the uniform distribution.
128 * @param maxval Upper bound of the uniform distribution.
129 * @param dtype
130 * @param seed
131 * @param name Optional name.
132 * @return The uniform-random Variable.
133 */
134export declare function randomUniformVariable(shape: Shape, minval: number, maxval: number, dtype?: DataType, seed?: number, name?: string): LayerVariable;
135/**
136 * Get a Variable with truncated-normal distribution of values.
137 * @param shape Shape of the tensor.
138 * @param mean mean value of the normal distribution.
139 * @param stddev standard deviation of the normal distribution.
140 * @param dtype
141 * @param seed
142 * @param name Optional name.
143 * @return The truncated-normal-random Variable.
144 */
145export declare function truncatedNormalVariable(shape: Shape, mean?: number, stddev?: number, dtype?: DataType, seed?: number, name?: string): LayerVariable;
146/**
147 * Get a Variable with normal distribution of values.
148 * @param shape Shape of the tensor.
149 * @param mean mean value of the normal distribution.
150 * @param stddev standard deviation of the normal distribution.
151 * @param dtype
152 * @param seed
153 * @param name Optional name.
154 * @return The truncated-normal-random Variable.
155 */
156export declare function randomNormalVariable(shape: Shape, mean?: number, stddev?: number, dtype?: DataType, seed?: number, name?: string): LayerVariable;
157/**
158 * Update the value of a Variable.
159 * @param x The Variable to be updated.
160 * @param xNew The new value to update to.
161 * @return The Variable updated.
162 */
163export declare function update(x: LayerVariable, xNew: Tensor): LayerVariable;
164/**
165 * Update the value of a Variable by adding an increment.
166 * @param x The Variable to be updated.
167 * @param increment The incrment to add to `x`.
168 * @return The Variable updated.
169 */
170export declare function updateAdd(x: LayerVariable, increment: Tensor): LayerVariable;
171/**
172 * Update the value of a Variable by subtracting a decrement.
173 * @param x The Variable to be updated.
174 * @param decrement The decrement to subtract from `x`.
175 * @return The Variable updated.
176 */
177export declare function updateSub(x: LayerVariable, decrement: Tensor): LayerVariable;
178/**
179 * Get the values of an array of Variables.
180 *
181 * @param tensors An `Array` of `Variable`s to get the values of.
182 * @return The values of the inputs, as an `Array` of`tf.Tensor`s.
183 */
184export declare function batchGetValue(xs: LayerVariable[]): Tensor[];
185/**
186 * Update the value of multiple Variables at once.
187 *
188 * @param variablesAndValues An `Array`, each element is of type
189 * [Variable, Tensor]. The first item is the
190 * `Variable` of which the value is to be updated. The second item
191 * carries the new value.
192 */
193export declare function batchSetValue(variablesAndValues: Array<[LayerVariable, Tensor]>): void;
194/**
195 * Returns the gradients of `variables` w.r.t. the return value of `lossFn`.
196 * @param lossFn A function which returns a Scalar to be used as the function
197 * value (i.e., numerator) for differentiation.
198 * @param variables List of variables to be used as the independent variables
199 * (i.e., denominator) for differentiation.
200 * @returns An Array of gradients tensors.
201 */
202export declare function gradients(lossFn: () => tfc.Scalar, variables: LayerVariable[]): Tensor[];