chore: import upstream snapshot with attribution

tools/onnx-graphsurgeon/examples/04_modifying_a_model/README.md

@@ -0,0 +1,37 @@
+# Modiyfing A Model
+
+## Introduction
+
+This example first generates a basic model,
+then modifies the resulting model in various ways.
+
+By importing an ONNX graph into the [ONNX GraphSurgeon IR](../../README.md#ir), it is
+possible to modify virtually every aspect of the graph.
+We can then export the modified IR back to ONNX.
+
+## Running the example
+
+1. Generate a model with several nodes and save it to `model.onnx` by running:
+    ```bash
+    python3 generate.py
+    ```
+
+    The generated model computes `Y = x0 + (a * x1 + b)`:
+
+    ![../resources/04_model.onnx.png](../resources/04_model.onnx.png)
+
+2. Modify the model in various ways, and save it to `modified.onnx` by running:
+    ```bash
+    python3 modify.py
+    ```
+
+    This script does the following:
+    - Removes the `b` input of the first `Add` node
+    - Changes the first `Add` to a `LeakyRelu`
+    - Adds an `Identity` node after the first `Add`
+    - Changes the output of the graph to be the output of the `Identity` node
+    - Runs `cleanup()` which removes the `x0` tensor and second `Add` node due to the previous change to the graph outputs.
+
+    The resulting graph computes `identity_out = leaky_relu(a * x1)`:
+
+    ![../resources/04_modified.onnx.png](../resources/04_modified.onnx.png)

tools/onnx-graphsurgeon/examples/04_modifying_a_model/generate.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+#
+# SPDX-FileCopyrightText: Copyright (c) 1993-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import onnx_graphsurgeon as gs
+import numpy as np
+import onnx
+
+# Computes Y = x0 + (a * x1 + b)
+
+shape = (1, 3, 224, 224)
+# Inputs
+x0 = gs.Variable(name="x0", dtype=np.float32, shape=shape)
+x1 = gs.Variable(name="x1", dtype=np.float32, shape=shape)
+
+# Intermediate tensors
+a = gs.Constant("a", values=np.ones(shape=shape, dtype=np.float32))
+b = gs.Constant("b", values=np.ones(shape=shape, dtype=np.float32))
+mul_out = gs.Variable(name="mul_out")
+add_out = gs.Variable(name="add_out")
+
+# Outputs
+Y = gs.Variable(name="Y", dtype=np.float32, shape=shape)
+
+nodes = [
+    # mul_out = a * x1
+    gs.Node(op="Mul", inputs=[a, x1], outputs=[mul_out]),
+    # add_out = mul_out + b
+    gs.Node(op="Add", inputs=[mul_out, b], outputs=[add_out]),
+    # Y = x0 + add
+    gs.Node(op="Add", inputs=[x0, add_out], outputs=[Y]),
+]
+
+graph = gs.Graph(nodes=nodes, inputs=[x0, x1], outputs=[Y], ir_version=10)
+onnx.save(gs.export_onnx(graph), "model.onnx")

tools/onnx-graphsurgeon/examples/04_modifying_a_model/modify.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+#
+# SPDX-FileCopyrightText: Copyright (c) 1993-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import onnx_graphsurgeon as gs
+import numpy as np
+import onnx
+
+graph = gs.import_onnx(onnx.load("model.onnx"))
+
+# 1. Remove the `b` input of the add node
+first_add = [node for node in graph.nodes if node.op == "Add"][0]
+first_add.inputs = [inp for inp in first_add.inputs if inp.name != "b"]
+
+# 2. Change the Add to a LeakyRelu
+first_add.op = "LeakyRelu"
+first_add.attrs["alpha"] = 0.02
+
+# 3. Add an identity after the add node
+identity_out = gs.Variable("identity_out", dtype=np.float32)
+identity = gs.Node(op="Identity", inputs=first_add.outputs, outputs=[identity_out])
+graph.nodes.append(identity)
+
+# 4. Modify the graph output to be the identity output
+graph.outputs = [identity_out]
+
+# 5. Remove unused nodes/tensors, and topologically sort the graph
+# ONNX requires nodes to be topologically sorted to be considered valid.
+# Therefore, you should only need to sort the graph when you have added new nodes out-of-order.
+# In this case, the identity node is already in the correct spot (it is the last node,
+# and was appended to the end of the list), but to be on the safer side, we can sort anyway.
+graph.cleanup(remove_unused_graph_inputs=True).toposort()
+
+model = onnx.shape_inference.infer_shapes(gs.export_onnx(graph))
+onnx.save(model, "modified.onnx")