Package: vgslify
VGSLify: Variable-size Graph Specification for TensorFlow & PyTorchVGSLify is a powerful toolkit designed to simplify the process of defining, training, and interpreting deep learning models using the Variable-size Graph Specification Language (VGSL). Inspired byTesseract's VGSL specs, VGSLify introduces a set of enhancements and provides a streamlined interface for both TensorFlow and, in future releases, PyTorch.Table of ContentsInstallationHow VGSL WorksQuick StartSupported Layers and Their SpecificationsFuture WorkContributingLicenseAcknowledgementsInstallationInstalling VGSLify is simple and straightforward. Follow the steps below to get started:1. PrerequisitesBefore installing VGSLify, ensure you have Python 3.8 or newer installed. You can check your Python version with the following command:python--versionIf you don't have Python installed, download it frompython.orgor use your system's package manager.2. Using pipThe easiest way to install VGSLify is viapip. Run the following command to install the latest version of VGSLify:pipinstallvgslify3. From SourceIf you want to install the development version or a modified version of VGSLify, you can do so from source. First, clone the repository or download the source code. Then navigate to the directory and run:pipinstall.4. Verifying InstallationAfter installation, you can verify that VGSLify was installed correctly by importing it in Python:python-c"import vgslify; print(vgslify.__version__)"This should print the installed version of VGSLify without any errors.Remember to periodically update VGSLify to benefit from new features and bug fixes. You can update it usingpip:pipinstall--upgradevgslifyHow VGSL worksVGSL operates through short definition strings. For instance:None,64,None,1 Cr3,3,32 Mp2,2,2,2 Cr3,3,64 Mp2,2,2,2 Rc Fc64 D20 Lrs128 D20 Lrs64 D20 O1s92In this example, the string defines a neural network with input layers, convolutional layers, pooling, reshaping, fully connected layers, LSTM and output layers. Each segment of the string corresponds to a specific layer or operation in the neural network. Moreover, VGSL provides the flexibility to specify the type of activation function for certain layers, enhancing customization.Quick StartUsing VGSLify, you can rapidly prototype TensorFlow models using the Variable-size Graph Specification Language (VGSL). Here's a simple example to get you started:Generating a TensorFlow Model with VGSLifyImport the Necessary Module:First, import theVGSLModelGeneratorclass from VGSLify's TensorFlow module.fromvgslify.tensorflow.generatorimportVGSLModelGeneratorInitialize the Model Generator:You can specify the architecture of the model using the VGSL spec string. For this example, let's create a model with a convolutional layer, max-pooling layer, and an output softmax layer:vgsl_spec="None,64,None,1 Cr3,3,32 Mp2,2,2,2 O1s92"vgsl_gn=VGSLModelGenerator(vgsl_spec)Build and View the Model:After specifying the model architecture, you can build and view the model summary.model=vgsl_gn.build()model.summary()This example demonstrates the simplicity of creating a TensorFlow model using VGSLify. The VGSL spec string allows you to define complex architectures with ease. For more details on the VGSL spec syntax and supported layers, refer to the "Supported Layers and Their Specifications" section.Creating Individual Layers with VGSLifyIn addition to creating complete models, VGSLify also allows you to generate individual TensorFlow layers using the VGSL spec. This is particularly useful when you want to integrate a VGSL-defined layer into an existing model or when you wish to experiment with individual components.Import the Necessary Module:Just like before, you'll need to import theVGSLModelGeneratorclass.fromvgslify.tensorflow.generatorimportVGSLModelGenerator**Generate an Individual Layer:To generate a layer, use the corresponding method on VGSLModelGenerator. The method name is the lowercase version of the desired layer name. For instance, to create a Conv2D layer, use VGSLModelGenerator.conv2d. Here's how you can generate a convolutional layer:vgsl_spec_for_conv2d="Cr3,3,64"conv2d_layer=VGSLModelGenerator.conv2d(vgsl_spec_for_conv2d)Optionally, you can also specify an initializer:importtensorflowastfconv2d_layer_with_initializer=VGSLModelGenerator.conv2d(vgsl_spec_for_conv2d,initializer=tf.keras.initializers.GlorotNormal)Converting TensorFlow Models to VGSLOnce you have trained a TensorFlow model, you might want to convert it back into a VGSL spec string for various purposes. VGSLify provides an easy way to do this:Load Your TensorFlow Model:If you've saved your trained Keras model to a file, first load it using TensorFlow'sload_modelmethod:importtensorflowastfmodel=tf.keras.models.load_model("path_to_your_model.h5")Convert to VGSL Spec String:With your model loaded, use theparse_tf_modelfunction from VGSLify to convert the model into a VGSL spec string:fromvgslify.parserimportparse_tf_modelvgsl_spec_string=parse_tf_model(model)print(vgsl_spec_string)This provides a concise representation of your model's architecture in VGSL format. Please note that while VGSLify aims to support a wide variety of architectures, there might be specific TensorFlow layers or configurations that are not supported. In such cases, aValueErrorwill be raised.Supported Layers and Their SpecificationsOverviewBelow is a concise table providing a summary of each supported layer:LayerSpecExampleDescriptionInputbatch,height,width,depthNone,64,None,1Input layer with variable batch size & width, and 1 channel depthOutputO(2|1|0)(l|s)O1s10Dense layer with a 1D sequence, 10 output classes, and softmax activationConv2DC(s|t|r|l|m),<x>,<y>[,<s_x>,<s_y>],<d>Cr3,3,64Conv2D layer with ReLU activation, 3x3 filter size, 1x1 stride, and 64 filtersDense (Fully Connected, FC)F(s|t|r|l|m)<d>Fs64Dense layer with softmax activation and 64 unitsLSTML(f|r)[s]<n>[,D<rate>][,Rd<rate>]Lf64sD25Rd10LSTM cell (forward-only) with 64 units, return sequences, 0.25 dropout, and 0.10 recurrent dropoutGRUG(f|r)[s]<n>[,D<rate>][,Rd<rate>]Gr64s,D20,Rd15GRU cell (reverse-only) with 64 units, return sequences, 0.20 dropout, and 0.15 recurrent dropoutBidirectionalB(g|l)<n>[,D<rate>][,Rd<rate>]Bl256,D15,Rd10Bidirectional layer wrapping an LSTM RNN with 256 units, 0.15 dropout, and 0.10 recurrent dropoutBatchNormalizationBnBnBatchNormalization layerMaxPooling2DMp<x>,<y>,<s_x>,<s_y>Mp2,2,1,1MaxPooling2D layer with 2x2 pool size and 1x1 stridesAvgPooling2DAp<x>,<y>,<s_x>,<s_y>Ap2,2,2,2AveragePooling2D layer with 2x2 pool size and 2x2 stridesDropoutD<rate>D25Dropout layer with a dropout rate of 0.25ReshapeRcRcReshape layer returns a new (collapsed) tf.Tensor based on the previous layer outputsNote: In the specs, the|symbol indicates options. For example, inO(2 | 1 | 0)(l | s), it means the output layer could beO2l,O1s, etc. Arguments between the[and]symbol indicate that this is optional. The[s]in RNN layers activatesreturn_sequences.For more detailed information about each layer and its associated VGSL spec, see the following sections:Layer DetailsInputSpec:batch,height,width,depthDescription: Represents the TensorFlow input layer, based on standard TF tensor dimensions.Example:None,64,None,1creates atf.keras.layers.Inputwith a variable batch size, height of 64, variable width, and a depth of 1 (input channels).OutputSpec:O(2|1|0)(l|s)<n>Description: Output layer providing either a 2D vector (heat) map of the input (2), a 1D sequence of vector values (1) or a 0D single vector value (0) withnclasses. Currently, only a 1D sequence of vector values is supported.Example:O1s10creates a Dense layer with a 1D sequence as output with 10 classes and softmax.Conv2DSpec:C(s|t|r|l|m)<x>,<y>[,<s_x>,<s_y>],<d>Description: Convolutional layer using ax,ywindow anddfilters. Optionally, the stride window can be set with (s_x,s_y).Examples:Cr3,3,64creates a Conv2D layer with a ReLU activation function, a 3x3 filter, 1x1 stride, and 64 filters.Cr3,3,1,3,128creates a Conv2D layer with a ReLU activation function, a 3x3 filter, 1x3 strides, and 128 filters.DenseSpec:F(s|t|r|e|l|m)<d>Description: Fully-connected layer withs|t|r|e|l|mnon-linearity anddunits.Example:Fs64creates a FC layer with softmax non-linearity and 64 units.LSTMSpec:L(f|r)[s]<n>[,D<rate>][,Rd<rate>]]Description: LSTM cell running either forward-only (f) or reversed-only (r), withnunits. Optionally, theratecan be set for thedropoutand/or therecurrent_dropout, whererateindicates a percentage between 0 and 100.Example:Lf64creates a forward-only LSTM cell with 64 units.GRUSpec:G(f|r)[s]<n>[,D<rate>][,Rd<rate>]Description: GRU cell running either forward-only (f) or reversed-only (r), withnunits. Optionally, theratecan be set for thedropoutand/or therecurrent_dropout, whererateindicates a percentage between 0 and 100.Example:Gf64creates a forward-only GRU cell with 64 units.BidirectionalSpec:B(g|l)<n>[,D<rate>][,Rd<rate>]Description: Bidirectional layer wrapping either a LSTM (l) or GRU (g) RNN layer, running in both directions, withnunits. Optionally, theratecan be set for thedropoutand/or therecurrent_dropout, whererateindicates a percentage between 0 and 100.Example:Bl256creates a Bidirectional RNN layer using a LSTM Cell with 256 units.BatchNormalizationSpec:BnDescription: A technique often used to standardize the inputs to a layer for each mini-batch. Helps stabilize the learning process.Example:Bnapplies a transformation maintaining mean output close to 0 and output standard deviation close to 1.MaxPooling2DSpec:Mp<x>,<y>,<s_x>,<s_y>Description: Downsampling technique using ax,ywindow. The window is shifted by stridess_x,s_y.Example:Mp2,2,2,2creates a MaxPooling2D layer with pool size (2,2) and strides of (2,2).AvgPooling2DSpec:Ap<x>,<y>,<s_x>,<s_y>Description: Downsampling technique using ax,ywindow. The window is shifted by stridess_x,s_y.Example:Ap2,2,2,2creates an AveragePooling2D layer with pool size (2,2) and strides of (2,2).DropoutSpec:D<rate>Description: Regularization layer that sets input units to 0 at a rate ofrateduring training. Used to prevent overfitting.Example:D50creates a Dropout layer with a dropout rate of 0.5 (D/100).ReshapeSpec:RcDescription: Reshapes the output tensor from the previous layer, making it compatible with RNN layers.Example:Rcapplies a specific transformation:layers.Reshape((-1, prev_layer_y * prev_layer_x)).Future WorkPyTorch Model SupportWhile the current version of VGSLify supports TensorFlow models, I recognize the growing popularity and capabilities of PyTorch in the deep learning community. In an upcoming release, I aim to expand VGSLify's capabilities to generate and parse PyTorch models using VGSL spec, providing a unified experience across both major deep learning frameworks.Custom Layer SupportTo make VGSLify even more versatile, I'm working on a feature that will allow users to define and integrate custom layers into the VGSL specification. This enhancement will empower users to seamlessly integrate specialized layers or proprietary architectures into their VGSL-defined models, further bridging the gap between rapid prototyping and production-ready models.ContributingI warmly welcome contributions to VGSLify! Whether you're fixing bugs, adding new features, or improving the documentation, your efforts will make VGSLify better for everyone.How to Contribute:Fork the Repository: Start by forking the VGSLify repository.Set Up Your Development Environment: Clone your fork to your local machine and set up the development environment.Make Your Changes: Implement your changes, improvements, or fixes.Submit a Pull Request: Once you're done with your changes, push them to your fork and submit a pull request. Please provide a clear description of the changes and their purpose.Create Issues: If you find bugs or want to suggest improvements, please create an issue in the repository.Please ensure that your contributions adhere to our coding standards and practices. Your efforts will help VGSLify grow and thrive!LicenseVGSLify is open-source software and is licensed under the MIT License. This means you can freely use, modify, and distribute it, provided you include the original copyright notice. For more details, you can refer to theLICENSEfile in the repository.AcknowledgementsA special thank you to:@Thelukepet: For his invaluable contributions to the codebase.The creators and contributors of the original VGSL specification, which inspired and laid the groundwork for VGSLify.