Merge pull request #17 from kengz/docs

fix: docs and demo examples

Author: kengz

README.md

@@ -290,19 +290,19 @@ File: [torcharc/example/spec/compact/mlp.yaml](torcharc/example/spec/compact/mlp
 #   mlp:
 #     Sequential:
 #       - LazyLinear:
-#           out_features: 128
-#       - ReLU:
-#       - LazyLinear:
-#           out_features: 128
+#           out_features: 64
 #       - ReLU:
 #       - LazyLinear:
 #           out_features: 64
 #       - ReLU:
 #       - LazyLinear:
 #           out_features: 32
 #       - ReLU:
+#       - LazyLinear:
+#           out_features: 16
+#       - ReLU:
 
-# the above is equivalent to the compact spec below
+# the above can be written compactly as follows
 
 modules:
   mlp:
@@ -396,7 +396,7 @@ File: [torcharc/example/spec/compact/conv.yaml](torcharc/example/spec/compact/co
 #       - LazyLinear:
 #           out_features: 10
 
-# the above is equivalent to the compact spec below
+# the above can be written compactly as follows
 
 modules:
   conv:

images/dlrm.png

@@ -1,6 +1,6 @@
 [project]
 name = "torcharc"
-version = "2.1.0"
+version = "2.1.1"
 description = "Build PyTorch models by specifying architectures."
 readme = "README.md"
 requires-python = ">=3.12"

pyproject.toml

@@ -6,8 +6,16 @@
 import torcharc
 
 # ================================================
-# Example: build model from spec file
+# To visualize model in Tensorboard, use the following
+# from torch.utils.tensorboard import SummaryWriter
+
+# writer = SummaryWriter(log_dir="tb_logs/mlp")
+# writer.add_graph(model, x)
+# writer.close()
 
+
+# ================================================
+# Example: build model from spec file
 filepath = Path(".") / "torcharc" / "example" / "spec" / "basic" / "mlp.yaml"
 
 # The following are equivalent:
@@ -52,6 +60,7 @@
 #   )
 # )
 
+
 # ================================================
 # Example: MLP (Lazy)
 # PyTorch Lazy layers will infer the input size from the first forward pass. This is recommended as it greatly simplifies the model definition.
@@ -95,6 +104,30 @@
 model
 
 
+# ================================================
+# Example: MLP (Compact)
+model = torcharc.build(torcharc.SPEC_DIR / "compact" / "mlp.yaml")
+
+# Run the model and check the output shape
+x = torch.randn(4, 128)
+y = model(x)
+assert y.shape == (4, 16)
+
+model
+
+
+# ================================================
+# Example: Conv (Compact)
+model = torcharc.build(torcharc.SPEC_DIR / "compact" / "conv_classifier.yaml")
+
+# Run the model and check the output shape
+x = torch.randn(4, 1, 28, 28)
+y = model(x)
+assert y.shape == (4, 10)
+
+model
+
+
 # ================================================
 # Example: Reuse syntax: Stereo Conv
 # To use the same module for many passes, specify with the reuse syntax in graph spec: <module>~<suffix>.

torcharc/example/notebook/demo.py

@@ -23,7 +23,7 @@
 #       - Dropout:
 #           p: 0.1
 
-# the above is equivalent to the compact spec below
+# the above can be written compactly as follows
 
 modules:
   conv:

torcharc/example/spec/compact/conv.yaml

@@ -28,7 +28,7 @@
 #       - LazyLinear:
 #           out_features: 10
 
-# the above is equivalent to the compact spec below
+# the above can be written compactly as follows
 
 modules:
   conv:

torcharc/example/spec/compact/conv_classifier.yaml

@@ -2,19 +2,19 @@
 #   mlp:
 #     Sequential:
 #       - LazyLinear:
-#           out_features: 128
-#       - ReLU:
-#       - LazyLinear:
-#           out_features: 128
+#           out_features: 64
 #       - ReLU:
 #       - LazyLinear:
 #           out_features: 64
 #       - ReLU:
 #       - LazyLinear:
 #           out_features: 32
 #       - ReLU:
+#       - LazyLinear:
+#           out_features: 16
+#       - ReLU:
 
-# the above is equivalent to the compact spec below
+# the above can be written compactly as follows
 
 modules:
   mlp:

torcharc/example/spec/compact/mlp.yaml

@@ -2,22 +2,22 @@
 #   mlp:
 #     Sequential:
 #       - LazyLinear:
-#           out_features: 128
-#       - ReLU:
-#       - LazyLinear:
-#           out_features: 128
+#           out_features: 64
 #       - ReLU:
 #       - LazyLinear:
 #           out_features: 64
 #       - ReLU:
 #       - LazyLinear:
 #           out_features: 32
 #       - ReLU:
+#       - LazyLinear:
+#           out_features: 16
+#       - ReLU:
 #   classifier:
 #     LazyLinear:
 #       out_features: 10
 
-# the above is equivalent to the compact spec below
+# the above can be written compactly as follows
 
 modules:
   mlp:
@@ -35,7 +35,6 @@ modules:
 graph:
   input: x
   modules:
-    # mlp: [x]
-    # classifier: mlp
-    classifier: [x]
+    mlp: [x]
+    classifier: [mlp]
   output: classifier