AI-MXNet
view release on metacpan or search on metacpan
lib/AI/MXNet/Symbol.pm view on Meta::CPAN
method list_auxiliary_states()
{
return scalar(check_call(AI::MXNetCAPI::SymbolListAuxiliaryStates($self->handle)));
}
=head2 list_inputs
Lists all arguments and auxiliary states of this Symbol.
Returns
-------
inputs : array ref of str
List of all inputs.
Examples
--------
>>> my $bn = mx->sym->BatchNorm(name=>'bn');
=cut
method list_inputs()
{
return scalar(check_call(AI::NNVMCAPI::SymbolListInputNames($self->handle, 0)));
}
=head2 infer_type
Infer the type of outputs and arguments of given known types of arguments.
User can either pass in the known types in positional way or keyword argument way.
Tuple of Nones is returned if there is not enough information passed in.
An error will be raised if there is inconsistency found in the known types passed in.
Parameters
----------
args : Array
Provide type of arguments in a positional way.
Unknown type can be marked as None
kwargs : Hash ref, must ne ssupplied as as sole argument to the method.
Provide keyword arguments of known types.
Returns
-------
arg_types : array ref of Dtype or undef
List of types of arguments.
The order is in the same order as list_arguments()
out_types : array ref of Dtype or undef
List of types of outputs.
The order is in the same order as list_outputs()
aux_types : array ref of Dtype or undef
List of types of outputs.
The order is in the same order as list_auxiliary()
=cut
method infer_type(Str|Undef @args)
{
my ($positional_arguments, $kwargs, $kwargs_order) = _parse_arguments("Dtype", @args);
my $sdata = [];
my $keys = [];
if(@$positional_arguments)
{
@{ $sdata } = map { defined($_) ? DTYPE_STR_TO_MX->{ $_ } : -1 } @{ $positional_arguments };
}
else
{
@{ $keys } = @{ $kwargs_order };
@{ $sdata } = map { DTYPE_STR_TO_MX->{ $_ } } @{ $kwargs }{ @{ $kwargs_order } };
}
my ($arg_type, $out_type, $aux_type, $complete) = check_call(AI::MXNetCAPI::SymbolInferType(
$self->handle,
scalar(@{ $sdata }),
$keys,
$sdata
)
);
if($complete)
{
return (
[ map { DTYPE_MX_TO_STR->{ $_ } } @{ $arg_type }],
[ map { DTYPE_MX_TO_STR->{ $_ } } @{ $out_type }],
[ map { DTYPE_MX_TO_STR->{ $_ } } @{ $aux_type }]
);
}
else
{
return (undef, undef, undef);
}
}
=head2 infer_shape
Infer the shape of outputs and arguments of given known shapes of arguments.
User can either pass in the known shapes in positional way or keyword argument way.
Tuple of Nones is returned if there is not enough information passed in.
An error will be raised if there is inconsistency found in the known shapes passed in.
Parameters
----------
*args :
Provide shape of arguments in a positional way.
Unknown shape can be marked as undef
**kwargs :
Provide keyword arguments of known shapes.
Returns
-------
arg_shapes : array ref of Shape or undef
List of shapes of arguments.
The order is in the same order as list_arguments()
out_shapes : array ref of Shape or undef
List of shapes of outputs.
The order is in the same order as list_outputs()
aux_shapes : array ref of Shape or undef
List of shapes of outputs.
The order is in the same order as list_auxiliary()
=cut
method infer_shape(Maybe[Str|Shape] @args)
{
my @res = $self->_infer_shape_impl(0, @args);
if(not defined $res[1])
{
my ($arg_shapes) = $self->_infer_shape_impl(1, @args);
my $arg_names = $self->list_arguments;
my @unknowns;
zip(sub {
my ($name, $shape) = @_;
if(not ref $shape or not @$shape or not product(@$shape))
{
if(@unknowns >= 10)
{
$unknowns[10] = '...';
}
else
{
my @shape = eval { @$shape };
push @unknowns, "$name @shape";
}
}
}, $arg_names, $arg_shapes);
AI::MXNet::Logging->warning(
"Cannot decide shape for the following arguments "
."(0s in shape means unknown dimensions). "
."Consider providing them as input:\n\t"
."\n\t"
.join(", ", @unknowns)
);
}
return @res;
}
=head2 infer_shape_partial
Partially infer the shape. The same as infer_shape, except that the partial
results can be returned.
=cut
method infer_shape_partial(Maybe[Str|Shape] @args)
{
$self->_infer_shape_impl(1, @args)
}
# The actual implementation for calling shape inference API.
method _infer_shape_impl(Maybe[Str|Shape] @args)
{
my $partial = shift(@args);
my ($positional_arguments, $kwargs, $kwargs_order) = _parse_arguments("Shape", @args);
my $sdata = [];
my $indptr = [0];
my $keys = [];
if(@{ $positional_arguments })
{
for my $shape (grep { defined } @{ $positional_arguments })
{
push @{ $sdata }, @{ $shape };
push @{ $indptr }, scalar(@{ $sdata });
}
}
{
for my $k (@{ $kwargs_order })
{
push @{ $keys }, $k;
push @{ $sdata }, @{ $kwargs->{ $k } };
push @{ $indptr }, scalar(@{ $sdata });
}
}
my $infer_func = $partial ? \&AI::MXNetCAPI::SymbolInferShapePartial : \&AI::MXNetCAPI::SymbolInferShape;
my ($arg_shapes, $out_shapes, $aux_shapes, $complete) = check_call(
$infer_func->(
$self->handle,
scalar(@{ $indptr }) - 1,
$keys,
$indptr,
$sdata,
)
);
if($complete)
{
return $arg_shapes, $out_shapes, $aux_shapes;
}
else
{
return (undef, undef, undef);
}
}
=head2 debug_str
The debug string.
Returns
-------
debug_str : string
Debug string of the symbol.
=cut
method debug_str()
{
return scalar(check_call(AI::MXNetCAPI::SymbolPrint($self->handle)));
}
=head2 save
Save the symbol into a file.
You can also use Storable to do the job if you only work with Perl.
The advantage of load/save is the file is language agnostic.
This means the file saved using save can be loaded by other language binding of mxnet.
You also get the benefit being able to directly load/save from cloud storage(S3, HDFS)
Parameters
----------
fname : str
The name of the file
- s3://my-bucket/path/my-s3-symbol
- hdfs://my-bucket/path/my-hdfs-symbol
- /path-to/my-local-symbol
See Also
--------
load : Used to load symbol from file.
=cut
method save(Str $fname)
{
check_call(AI::MXNetCAPI::SymbolSaveToFile($self->handle, $fname));
}
=head2 tojson
Save the symbol into a JSON string.
See Also
--------
load_json : Used to load symbol from JSON string.
=cut
method tojson()
{
return scalar(check_call(AI::MXNetCAPI::SymbolSaveToJSON($self->handle)));
}
method _get_ndarray_inputs(
Str $arg_key,
HashRef[AI::MXNet::NDArray]|ArrayRef[AI::MXNet::NDArray] $args,
ArrayRef[Str] $arg_names,
Bool $allow_missing=0
)
{
my ($arg_handles, $arg_arrays) = ([], []);
if(ref $args eq 'ARRAY')
{
confess("Length of $arg_key do not match number of arguments")
unless @$args == @$arg_names;
@{ $arg_handles } = map { $_->handle } @{ $args };
$arg_arrays = $args;
}
else
{
my %tmp = ((map { $_ => undef } @$arg_names), %$args);
if(not $allow_missing and grep { not defined } values %tmp)
{
my ($missing) = grep { not defined $tmp{ $_ } } (keys %tmp);
confess("key $missing is missing in $arg_key");
}
for my $name (@$arg_names)
{
push @$arg_handles, defined($tmp{ $name }) ? $tmp{ $name }->handle : undef;
push @$arg_arrays, defined($tmp{ $name }) ? $tmp{ $name } : undef;
}
}
return ($arg_handles, $arg_arrays);
}
=head2 simple_bind
Bind current symbol to get an executor, allocate all the ndarrays needed.
Allows specifying data types.
This function will ask user to pass in ndarray of position
they like to bind to, and it will automatically allocate the ndarray
for arguments and auxiliary states that user did not specify explicitly.
Parameters
----------
:$ctx : AI::MXNet::Context
The device context the generated executor to run on.
:$grad_req: string
{'write', 'add', 'null'}, or list of str or dict of str to str, optional
Specifies how we should update the gradient to the args_grad.
- 'write' means everytime gradient is write to specified args_grad NDArray.
- 'add' means everytime gradient is add to the specified NDArray.
- 'null' means no action is taken, the gradient may not be calculated.
:$type_dict : hash ref of str->Dtype
Input type map, name->dtype
:$group2ctx : hash ref of string to AI::MXNet::Context
The mapping of the ctx_group attribute to the context assignment.
:$shapes : hash ref of str->Shape
Input shape map, name->shape
:$shared_arg_names : Maybe[ArrayRef[Str]]
The argument names whose 'NDArray' of shared_exec can be reused for initializing
the current executor.
:$shared_exec : Maybe[AI::MXNet::Executor]
The executor whose arg_arrays, arg_arrays, grad_arrays, and aux_arrays can be
reused for initializing the current executor.
:$shared_buffer : Maybe[HashRef[AI::MXNet::NDArray]]
The dict mapping argument names to the `NDArray` that can be reused for initializing
the current executor. This buffer will be checked for reuse if one argument name
of the current executor is not found in `shared_arg_names`.
Returns
-------
$executor : AI::MXNet::Executor
The generated Executor
=cut
method simple_bind(
AI::MXNet::Context :$ctx=AI::MXNet::Context->current_ctx,
GradReq|ArrayRef[GradReq]|HashRef[GradReq] :$grad_req='write',
Maybe[HashRef[Shape]] :$shapes=,
Maybe[HashRef[Dtype]] :$type_dict=,
Maybe[HashRef[AI::MXNet::Context]] :$group2ctx=,
Maybe[ArrayRef[Str]] :$shared_arg_names=,
Maybe[AI::MXNet::Executor] :$shared_exec=,
Maybe[HashRef[AI::MXNet::NDArray]] :$shared_buffer=
)
{
my $num_provided_arg_types;
my @provided_arg_type_names;
my @provided_arg_type_data;
if(defined $type_dict)
{
while(my ($k, $v) = each %{ $type_dict })
{
push @provided_arg_type_names, $k;
push @provided_arg_type_data, DTYPE_STR_TO_MX->{$v};
}
$num_provided_arg_types = @provided_arg_type_names;
}
my @provided_arg_shape_data;
# argument shape index in sdata,
# e.g. [sdata[indptr[0]], sdata[indptr[1]]) is the shape of the first arg
my @provided_arg_shape_idx = (0);
my @provided_arg_shape_names;
while(my ($k, $v) = each %{ $shapes//{} })
{
push @provided_arg_shape_names, $k;
push @provided_arg_shape_data, @{ $v };
push @provided_arg_shape_idx, scalar(@provided_arg_shape_data);
}
$num_provided_arg_types = @provided_arg_type_names;
my $provided_req_type_list_len = 0;
my @provided_grad_req_types;
my @provided_grad_req_names;
if(defined $grad_req)
{
if(not ref $grad_req)
{
push @provided_grad_req_types, $grad_req;
}
elsif(ref $grad_req eq 'ARRAY')
{
assert((@{ $grad_req } != 0), 'grad_req in simple_bind cannot be an empty list');
@provided_grad_req_types = @{ $grad_req };
$provided_req_type_list_len = @provided_grad_req_types;
}
elsif(ref $grad_req eq 'HASH')
{
assert((keys %{ $grad_req } != 0), 'grad_req in simple_bind cannot be an empty hash');
while(my ($k, $v) = each %{ $grad_req })
{
push @provided_grad_req_names, $k;
push @provided_grad_req_types, $v;
}
$provided_req_type_list_len = @provided_grad_req_types;
}
}
my $num_ctx_map_keys = 0;
my @ctx_map_keys;
my @ctx_map_dev_types;
my @ctx_map_dev_ids;
if(defined $group2ctx)
{
while(my ($k, $v) = each %{ $group2ctx })
{
push @ctx_map_keys, $k;
push @ctx_map_dev_types, $v->device_type_id;
push @ctx_map_dev_ids, $v->device_id;
}
$num_ctx_map_keys = @ctx_map_keys;
}
my @shared_arg_name_list;
if(defined $shared_arg_names)
{
@shared_arg_name_list = @{ $shared_arg_names };
}
my %shared_data;
if(defined $shared_buffer)
{
while(my ($k, $v) = each %{ $shared_buffer })
{
$shared_data{$k} = $v->handle;
}
}
my $shared_exec_handle = defined $shared_exec ? $shared_exec->handle : undef;
my (
$updated_shared_data,
$in_arg_handles,
$arg_grad_handles,
$aux_state_handles,
$exe_handle
);
eval {
($updated_shared_data, $in_arg_handles, $arg_grad_handles, $aux_state_handles, $exe_handle)
=
check_call(
AI::MXNetCAPI::ExecutorSimpleBind(
$self->handle,
$ctx->device_type_id,
$ctx->device_id,
$num_ctx_map_keys,
\@ctx_map_keys,
\@ctx_map_dev_types,
\@ctx_map_dev_ids,
$provided_req_type_list_len,
\@provided_grad_req_names,
\@provided_grad_req_types,
scalar(@provided_arg_shape_names),
\@provided_arg_shape_names,
\@provided_arg_shape_data,
\@provided_arg_shape_idx,
$num_provided_arg_types,
\@provided_arg_type_names,
\@provided_arg_type_data,
scalar(@shared_arg_name_list),
\@shared_arg_name_list,
defined $shared_buffer ? \%shared_data : undef,
$shared_exec_handle
)
);
};
if($@)
{
confess(
"simple_bind failed: Error: $@; Arguments: ".
Data::Dumper->new(
[$shapes//{}]
)->Purity(1)->Deepcopy(1)->Terse(1)->Dump
);
}
if(defined $shared_buffer)
{
while(my ($k, $v) = each %{ $updated_shared_data })
{
$shared_buffer->{$k} = AI::MXNet::NDArray->new(handle => $v);
}
}
my @arg_arrays = map { AI::MXNet::NDArray->new(handle => $_) } @{ $in_arg_handles };
my @grad_arrays = map { defined $_ ? AI::MXNet::NDArray->new(handle => $_) : undef } @{ $arg_grad_handles };
my @aux_arrays = map { AI::MXNet::NDArray->new(handle => $_) } @{ $aux_state_handles };
my $executor = AI::MXNet::Executor->new(
handle => $exe_handle,
symbol => $self,
ctx => $ctx,
grad_req => $grad_req,
group2ctx => $group2ctx
);
$executor->arg_arrays(\@arg_arrays);
$executor->grad_arrays(\@grad_arrays);
$executor->aux_arrays(\@aux_arrays);
return $executor;
}
=head2 bind
Bind current symbol to get an executor.
Parameters
----------
:$ctx : AI::MXNet::Context
The device context the generated executor to run on.
:$args : HashRef[AI::MXNet::NDArray]|ArrayRef[AI::MXNet::NDArray]
Input arguments to the symbol.
- If type is array ref of NDArray, the position is in the same order of list_arguments.
- If type is hash ref of str to NDArray, then it maps the name of arguments
to the corresponding NDArray.
- In either case, all the arguments must be provided.
:$args_grad : Maybe[HashRef[AI::MXNet::NDArray]|ArrayRef[AI::MXNet::NDArray]]
When specified, args_grad provide NDArrays to hold
the result of gradient value in backward.
- If type is array ref of NDArray, the position is in the same order of list_arguments.
- If type is hash ref of str to NDArray, then it maps the name of arguments
to the corresponding NDArray.
- When the type is hash ref of str to NDArray, users only need to provide the dict
for needed argument gradient.
Only the specified argument gradient will be calculated.
:$grad_req : {'write', 'add', 'null'}, or array ref of str or hash ref of str to str, optional
Specifies how we should update the gradient to the args_grad.
- 'write' means everytime gradient is write to specified args_grad NDArray.
- 'add' means everytime gradient is add to the specified NDArray.
- 'null' means no action is taken, the gradient may not be calculated.
:$aux_states : array ref of NDArray, or hash ref of str to NDArray, optional
Input auxiliary states to the symbol, only need to specify when
list_auxiliary_states is not empty.
- If type is array ref of NDArray, the position is in the same order of list_auxiliary_states
- If type is hash ref of str to NDArray, then it maps the name of auxiliary_states
to the corresponding NDArray,
- In either case, all the auxiliary_states need to be provided.
lib/AI/MXNet/Symbol.pm view on Meta::CPAN
$ctx->device_type_id,
$ctx->device_id,
scalar(@{ $ctx_map_keys }),
$ctx_map_keys,
$ctx_map_dev_types,
$ctx_map_dev_ids,
scalar(@{ $args }),
$args_handle,
$args_grad_handle,
$req_array,
scalar(@{ $aux_states }),
$aux_args_handle,
$shared_handle
)
);
my $executor = AI::MXNet::Executor->new(
handle => $handle,
symbol => $self,
ctx => $ctx,
grad_req => $grad_req,
group2ctx => $group2ctx
);
$executor->arg_arrays($args);
$executor->grad_arrays($args_grad);
$executor->aux_arrays($aux_states);
return $executor;
}
=head2 eval
Evaluate a symbol given arguments
The `eval` method combines a call to `bind` (which returns an executor)
with a call to `forward` (executor method).
For the common use case, where you might repeatedly evaluate with same arguments,
eval is slow.
In that case, you should call `bind` once and then repeatedly call forward.
Eval allows simpler syntax for less cumbersome introspection.
Parameters
----------
:$ctx : Context
The device context the generated executor to run on.
Optional, defaults to cpu(0)
:$args array ref of NDArray or hash ref of NDArray
- If the type is an array ref of NDArray, the position is in the same order of list_arguments.
- If the type is a hash of str to NDArray, then it maps the name of the argument
to the corresponding NDArray.
- In either case, all arguments must be provided.
Returns
----------
result : an array ref of NDArrays corresponding to the values
taken by each symbol when evaluated on given args.
When called on a single symbol (not a group),
the result will be an array ref with one element.
Examples:
my $result = $symbol->eval(ctx => mx->gpu, args => {data => mx->nd->ones([5,5])});
my $result = $symbol->eval(args => {data => mx->nd->ones([5,5])});
=cut
method eval(:$ctx=AI::MXNet::Context->cpu, HashRef[AI::MXNet::NDArray]|ArrayRef[AI::MXNet::NDArray] :$args)
{
return $self->bind(ctx => $ctx, args => $args)->forward;
}
=head2 grad
Get the autodiff of current symbol.
This function can only be used if current symbol is a loss function.
Parameters
----------
$wrt : Array of String
keyword arguments of the symbol that the gradients are taken.
Returns
-------
grad : AI::MXNet::Symbol
A gradient Symbol with returns to be the corresponding gradients.
=cut
method grad(ArrayRef[Str] $wrt)
{
my $handle = check_call(AI::MXNetCAPI::SymbolGrad(
$self->handle,
scalar(@$wrt),
$wrt
)
);
return __PACKAGE__->new(handle => $handle);
}
=head2 Variable
Create a symbolic variable with specified name.
Parameters
----------
name : str
Name of the variable.
attr : hash ref of string -> string
Additional attributes to set on the variable.
shape : array ref of positive integers
Optionally, one can specify the shape of a variable. This will be used during
shape inference. If user specified a different shape for this variable using
keyword argument when calling shape inference, this shape information will be ignored.
lr_mult : float
Specify learning rate muliplier for this variable.
wd_mult : float
Specify weight decay muliplier for this variable.
dtype : Dtype
Similar to shape, we can specify dtype for this variable.
init : initializer (mx->init->*)
Specify initializer for this variable to override the default initializer
kwargs : hash ref
other additional attribute variables
Returns
( run in 3.497 seconds using v1.01-cache-2.11-cpan-140bd7fdf52 )