# Model Summary

This describes how to summarize an ML model using the MLTK's commands/APIs.

```{note}
_Any_  `.tflite` or `.h5` model file will work with the model summary generation.  
i.e. The model file does _not_ need to be generated by the MLTK to generate a summary of it.
```


## Quick Reference

- Command-line: [mltk summarize --help](../command_line/summarize.md)
- Python API: [summarize_model](mltk.core.summarize_model)
- Python API examples: [summarize_model.ipynb](../../mltk/examples/summarize_model.ipynb)


## Overview

The MLTK's model summary feature generates a text summary of a model containing some or all of the following information:
- Model layout including each layer's name/type/output shape
- Number of trainable parameters
- Number of multiply-accumulate (MAC) operations
- Number of operations
- Any additional [model parameters](./model_parameters.md)


### Keras Model vs Tensorflow-Lite Model Summary

Two types of model summaries may be generated:
- __Keras Model__ - This provides a summary of the exact model used for training, file extension: `.h5`
- __Tensorflow-Lite Model__ - This provides a summary of the [converted](https://www.tensorflow.org/lite/convert), quantized model that can execute on an embedded device, file extension: `.tflite` (see [Model Quantization](./model_quantization.md))

Both these models have similar model layouts, however, the Tensorflow-Lite model is slightly modified to optimize it for embedded execution.

The Keras Model summary is generated by [KerasModel.summary()](https://keras.io/api/models/model/#summary-method) API,  
while the Tensorflow-Lite Model is generated by the [TfliteModel.summary()](mltk.core.TfliteModel.summary) API.

By default, the `summarize` command or [summarize_model](mltk.core.summarize_model) API will generate a summary of the trained `.h5` model in the [model archive](./model_archive.md) file.   
Specify the `--tflite` option to summarize the trained `.tflite` model in [model archive](./model_archive.md) file.

Alternatively, provide the `--build` option to summarize the model _without_ training first.  
Alternatively, provide the path to a `.tflite` or `.h5` model file to summarize a non-MLTK generated model file.


## Command

Model summarization from the command-line is done using the `summarize` operation.

For more details on the available command-line options, issue the command:

```shell
mltk summarize --help
```

### Example 1: Summarize Keras model

In this example, we generate a summary of the trained `.h5` model file in the 
[image_classification](mltk.models.tinyml.image_classification) model's [model archive](./model_archive.md).

```shell
mltk summarize image_classification
```

### Example 2: Summarize Tensorflow-Lite model

In this example, we generate a summary of the trained `.tflite` model file in the 
[image_classification](mltk.models.tinyml.image_classification) model's [model archive](./model_archive.md).


```shell
mltk summarize image_classification --tflite
```

### Example 3: Summarize external Tensorflow-Lite model

The given model need _not_ be generated by the MLTK. 
External models are also supported by the `summarize` command:

```shell
mltk summarize ~/workspace/my_model.tflite
```

### Example 4: Summarize model before training

Training a model can be very time-consuming, and it is useful to know basic information 
about a model before investing time and energy into training it.
For this reason, the MLTK `summarize` command features a `--build` flag to build a model
and summarize it _before_ the model is fully trained.

In this example, the [image_classification](mltk.models.tinyml.image_classification) model is built
at command-execution-time and a summarize is generated.
Note that _only_ the [model specification](./model_specification.md) script is required, 
it does _not_ need to be trained first.

```shell
mltk summarize image_classification --tflite --build
```



## Python API

Model summarization is accessible via the [summarize_model](mltk.core.summarize_model) API.

Examples using this API may be found in [summarize_model.ipynb](../../mltk/examples/summarize_model.ipynb)