Compute Library
 21.08
CommonGraphOptions.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018-2021 Arm Limited.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all
14  * copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  */
24 #ifndef ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS
25 #define ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS
26 
29 
33 
34 namespace arm_compute
35 {
36 namespace utils
37 {
38 /* ![Common graph examples parameters] */
39 /* Common graph parameters
40  *
41  * --help : Print the example's help message.
42  * --threads : The number of threads to be used by the example during execution.
43  * --target : Execution target to be used by the examples. Supported target options: Neon, CL, CLVK.
44  * --type : Data type to be used by the examples. Supported data type options: QASYMM8, F16, F32.
45  * --layout : Data layout to be used by the examples. Supported data layout options : NCHW, NHWC.
46  * --enable-tuner : Toggle option to enable the OpenCL dynamic tuner.
47  * --enable-cl-cache : Toggle option to load the prebuilt opencl kernels from a cache file.
48  * --fast-math : Toggle option to enable the fast math option.
49  * --data : Path that contains the trainable parameter files of graph layers.
50  * --image : Image to load and operate on. Image types supported: PPM, JPEG, NPY.
51  * --labels : File that contains the labels that classify upon.
52  * --validation-file : File that contains a list of image names with their corresponding label id (e.g. image0.jpg 5).
53  * This is used to run the graph over a number of images and report top-1 and top-5 metrics.
54  * --validation-path : The path where the validation images specified in the validation file reside.
55  * --validation-range : The range of the images to validate from the validation file (e.g 0,9).
56  * If not specified all the images will be validated.
57  * --tuner-file : The file to store the OpenCL dynamic tuner tuned parameters.
58  * --tuner-mode : Select tuner mode. Supported modes: Exhaustive,Normal,Rapid
59  * * Exhaustive: slowest but produces the most performant LWS configuration.
60  * * Normal: slow but produces the LWS configurations on par with Exhaustive most of the time.
61  * * Rapid: fast but produces less performant LWS configurations
62  *
63  * Note that data, image and labels options should be provided to perform an inference run on an image.
64  * Note that validation-file and validation-path should be provided to perform a graph accuracy estimation.
65  *
66  * Example execution commands:
67  *
68  * Execute a single inference given an image and a file containing the correspondence between label ids and human readable labels:
69  * ./graph_vgg16 --data=data/ --target=cl --layout=nhwc --image=kart.jpeg --labels=imagenet1000_clsid_to_human.txt
70  *
71  * Perform a graph validation on a list of images:
72  * ./graph_vgg16 --data=data/ --target=neon --threads=4 --layout=nchw --validation-file=val.txt --validation-path=ilsvrc_test_images/
73  *
74  * File formats:
75  *
76  * Validation file should be a plain file containing the names of the images followed by the correct label id.
77  * For example:
78  *
79  * image0.jpeg 882
80  * image1.jpeg 34
81  * image2.jpeg 354
82  *
83  * Labels file should be a plain file where each line is the respective human readable label (counting starts from 0).
84  * For example:
85  *
86  * 0: label0_name label0_name
87  * 1: label1_name or label1_name
88  * 2: label2_name label2_name
89  */
90 /* ![Common graph examples parameters] */
91 
92 /** Structure holding all the common graph parameters */
94 {
95  bool help{ false };
96  int threads{ 0 };
97  int batches{ 1 };
101  bool enable_tuner{ false };
102  bool enable_cl_cache{ false };
105  std::string data_path{};
106  std::string image{};
107  std::string labels{};
108  std::string validation_file{};
109  std::string validation_path{};
110  std::string tuner_file{};
111  std::string mlgo_file{};
112  unsigned int validation_range_start{ 0 };
113  unsigned int validation_range_end{ std::numeric_limits<unsigned int>::max() };
114 };
115 
116 /** Formatted output of the CommonGraphParams type
117  *
118  * @param[out] os Output stream.
119  * @param[in] common_params Common parameters to output
120  *
121  * @return Modified output stream.
122  */
123 ::std::ostream &operator<<(::std::ostream &os, const CommonGraphParams &common_params);
124 
125 /** Common command line options used to configure the graph examples
126  *
127  * The options in this object get populated when "parse()" is called on the parser used to construct it.
128  * The expected workflow is:
129  *
130  * CommandLineParser parser;
131  * CommonOptions options( parser );
132  * parser.parse(argc, argv);
133  */
135 {
136 public:
137  /** Constructor
138  *
139  * @param[in,out] parser A parser on which "parse()" hasn't been called yet.
140  */
142  /** Prevent instances of this class from being copied (As this class contains pointers) */
143  CommonGraphOptions(const CommonGraphOptions &) = delete;
144  /** Prevent instances of this class from being copied (As this class contains pointers) */
145  CommonGraphOptions &operator=(const CommonGraphOptions &) = delete;
146  /** Allow instances of this class to be moved */
148  /** Allow instances of this class to be moved */
149  CommonGraphOptions &operator=(CommonGraphOptions &&) = default;
150  /** Default destructor */
151  ~CommonGraphOptions() = default;
152 
153  ToggleOption *help; /**< Show help option */
154  SimpleOption<int> *threads; /**< Number of threads option */
155  SimpleOption<int> *batches; /**< Number of batches */
156  EnumOption<arm_compute::graph::Target> *target; /**< Graph execution target */
159  ToggleOption *enable_tuner; /**< Enable tuner */
160  ToggleOption *enable_cl_cache; /**< Enable opencl kernels cache */
162  ToggleOption *fast_math_hint; /**< Fast math hint */
163  SimpleOption<std::string> *data_path; /**< Trainable parameters path */
166  SimpleOption<std::string> *validation_file; /**< Validation file */
167  SimpleOption<std::string> *validation_path; /**< Validation data path */
168  SimpleOption<std::string> *validation_range; /**< Validation range */
169  SimpleOption<std::string> *tuner_file; /**< File to load/store the tuner's values from */
170  SimpleOption<std::string> *mlgo_file; /**< File to load the MLGO heuristics from */
171 };
172 
173 /** Consumes the common graph options and creates a structure containing any information
174  *
175  * @param[in] options Options to consume
176  *
177  * @return Structure containing the common graph parameters
178  */
180 } // namespace utils
181 } // namespace arm_compute
182 #endif /* ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS */
Arm® Neon™ capable target device.
ToggleOption * enable_tuner
Enable tuner.
SimpleOption< arm_compute::CLTunerMode > * tuner_mode
Tuner mode.
ToggleOption * help
Show help option.
SimpleOption< std::string > * mlgo_file
File to load the MLGO heuristics from.
EnumOption< arm_compute::DataType > * data_type
Graph data type.
EnumOption< arm_compute::DataLayout > * data_layout
Graph data layout.
Implementation of an option that can be either true or false.
Definition: ToggleOption.h:36
1 channel, 1 F32 per channel
Searches a subset of LWS configurations while tuning.
inline ::std::ostream & operator<<(::std::ostream &os, ConvolutionPaddingMode Mode)
Formatted output of the ConvolutionPaddingMode type.
void consume_common_graph_parameters(CommonGraphValidateOptions &options, CommonParams &common_params)
Consumes the consume_common_graph_parameters graph options and creates a structure containing any inf...
Common command line options used to configure the graph examples.
SimpleOption< std::string > * tuner_file
File to load/store the tuner&#39;s values from.
Class to parse command line arguments.
Copyright (c) 2017-2021 Arm Limited.
EnumOption< arm_compute::graph::Target > * target
Graph execution target.
Fast math disabled for Convolution layer.
ToggleOption * enable_cl_cache
Enable opencl kernels cache.
SimpleOption< int > * batches
Number of batches.
ToggleOption * fast_math_hint
Fast math hint.
SimpleOption< std::string > * validation_file
Validation file.
FastMathHint
Enable or disable fast math for Convolution layer.
Definition: Types.h:142
Structure holding all the common graph parameters.
SimpleOption< std::string > * validation_path
Validation data path.
CLTunerMode
< OpenCL tuner modes
Definition: CLTunerTypes.h:35
Num samples, height, width, channels.
SimpleOption< std::string > * validation_range
Validation range.
SimpleOption< std::string > * data_path
Trainable parameters path.
SimpleOption< std::string > * labels
Labels.
DataType
Available data types.
Definition: Types.h:77
SimpleOption< int > * threads
Number of threads option.
DataLayout
[DataLayout enum definition]
Definition: Types.h:111
arm_compute::graph::FastMathHint fast_math_hint
SimpleOption< std::string > * image
Image.