1# Licensed to the Apache Software Foundation (ASF) under one
2# or more contributor license agreements.  See the NOTICE file
3# distributed with this work for additional information
4# regarding copyright ownership.  The ASF licenses this file
5# to you under the Apache License, Version 2.0 (the
6# "License"); you may not use this file except in compliance
7# with the License.  You may obtain a copy of the License at
8#
9#   http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing,
12# software distributed under the License is distributed on an
13# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14# KIND, either express or implied.  See the License for the
15# specific language governing permissions and limitations
16# under the License.
17
18package AI::MXNet::Gluon;
19use strict;
20use warnings;
21use AI::MXNet::NS 'global';
22use AI::MXNet::Gluon::Loss 'loss';
23use AI::MXNet::Gluon::Trainer;
24use AI::MXNet::Gluon::Utils;
25use AI::MXNet::Gluon::Data 'data';
26use AI::MXNet::Gluon::NN 'nn';
27use AI::MXNet::Gluon::RNN 'rnn';
28
29sub utils { 'AI::MXNet::Gluon::Utils' }
30sub model_zoo { require AI::MXNet::Gluon::ModelZoo; 'AI::MXNet::Gluon::ModelZoo' }
31
32=head1 NAME
33
34    AI::MXNet::Gluon - High-level interface for MXNet.
35=cut
36
37=head1 DESCRIPTION
38
39    The AI::MXNet::Gluon package is a high-level interface for MXNet designed to be easy to use,
40    while keeping most of the flexibility of a low level API.
41    AI::MXNet::Gluon supports both imperative and symbolic programming,
42    making it easy to train complex models imperatively in Perl.
43
44    Based on the Gluon API specification,
45    the Gluon API in Apache MXNet provides a clear, concise, and simple API for deep learning.
46    It makes it easy to prototype, build, and train deep learning models without sacrificing training speed.
47
48    Advantages.
49
50    Simple, Easy-to-Understand Code: Gluon offers a full set of plug-and-play neural network building blocks,
51    including predefined layers, optimizers, and initializers.
52
53    Flexible, Imperative Structure: Gluon does not require the neural network model to be rigidly defined,
54    but rather brings the training algorithm and model closer together to provide flexibility in the development process.
55
56    Dynamic Graphs: Gluon enables developers to define neural network models that are dynamic,
57    meaning they can be built on the fly, with any structure, and using any of Perl's native control flow.
58
59    High Performance: Gluon provides all of the above benefits without impacting the training speed that the underlying engine provides.
60
61
62    Simple, Easy-to-Understand Code
63    Use plug-and-play neural network building blocks, including predefined layers, optimizers, and initializers:
64
65    use AI::MXNet qw(mx);
66    use AI::MXNet::Gluon qw(gluon);
67
68    my $net = gluon->nn->Sequential;
69    # When instantiated, Sequential stores a chain of neural network layers.
70    # Once presented with data, Sequential executes each layer in turn, using
71    # the output of one layer as the input for the next
72    $net->name_scope(sub {
73        $net->add(gluon->nn->Dense(256, activation=>"relu")); # 1st layer (256 nodes)
74        $net->add(gluon->nn->Dense(256, activation=>"relu")); # 2nd hidden layer
75        $net->add(gluon->nn->Dense($num_outputs));
76    });
77
78    Flexible, Imperative Structure.
79
80    Prototype, build, and train neural networks in fully imperative manner using the AI::MXNet::MXNet package and the Gluon trainer method:
81
82    use AI::MXNet::Base; # provides helpers, such as zip, enumerate, etc.
83    use AI::MXNet::AutoGrad qw(autograd);
84    my $epochs = 10;
85
86    for(1..$epochs)
87    {
88        for(zip($train_data))
89        {
90            my ($data, $label) = @$_;
91            autograd->record(sub {
92                my $output = $net->($data); # the forward iteration
93                my $loss = gluon->loss->softmax_cross_entropy($output, $label);
94                $loss->backward;
95            });
96            $trainer->step($data->shape->[0]); ## batch size
97        }
98    }
99
100    Dynamic Graphs.
101
102    Build neural networks on the fly for use cases where neural networks must change in size and shape during model training:
103
104    use AI::MXNet::Function::Parameters;
105
106    method forward(GluonClass $F, GluonInput $inputs, GluonInput :$tree)
107    {
108        my $children_outputs = [
109            map { $self->forward($F, $inputs, $_) @{ $tree->children }
110        ];
111        #Recursively builds the neural network based on each input sentence
112        #syntactic structure during the model definition and training process
113        ...
114    }
115
116    High Performance
117
118    Easily cache the neural network to achieve high performance by defining your neural network with HybridSequential
119    and calling the hybridize method:
120
121    use AI::MXNet::Gluon::NN qw(nn);
122
123    my $net = nn->HybridSequential;
124    $net->name_scope(sub {
125        $net->add(nn->Dense(256, activation=>"relu"));
126        $net->add(nn->Dense(128, activation=>"relu"));
127        $net->add(nn->Dense(2));
128    });
129
130    $net->hybridize();
131    See more at L<Python docs|https://mxnet.apache.org/api/python/docs/tutorials/packages/gluon/index.html>
132=cut
133
1341;
135