[Circuit] Add get_instance method

magma/circuit.py

@@ -27,7 +27,12 @@
     pass
 
 from magma.clock import is_clock_or_nested_clock, Clock, ClockTypes
-from magma.common import only, IterableException
+from magma.common import (
+    only,
+    IterableException,
+    EmptyIterableException,
+    NonSingletonIterableException,
+)
 from magma.config import get_debug_mode, set_debug_mode, config, RuntimeConfig
 from magma.definition_context import (
     DefinitionContext,
@@ -758,6 +763,15 @@ def is_definition(self):
     def instances(self):
         return self._context_.placer.instances()
 
+    def get_instance(self, name: str) -> 'AnonymousCircuitType':
+        instances = self.instances
+        try:
+            return only(filter(lambda i: i.name == name, instances))
+        except EmptyIterableException:
+            raise KeyError(name) from None
+        except NonSingletonIterableException:
+            raise KeyError(f"Found multiple instances with name '{name}'")
+
     @property
     def logs(self):
         return self._context_.logs

tests/test_circuit/test_instance.py

@@ -68,3 +68,20 @@ class Foo(m.Circuit):
         Foo.bar
 
     assert "has no attribute 'bar'" in str(e)
+
+
+def test_get_instance_method():
+
+    Bar = m.Register(m.Bit)  # just any module
+
+    class Foo(m.Circuit):
+        my_placeholder_var = Bar(name="my_instance_name")
+        Bar(name="duplicated")
+        Bar(name="duplicated")
+        my_instance_name = None
+
+    assert Foo.get_instance("my_instance_name") is Foo.my_placeholder_var
+    with pytest.raises(KeyError):
+        Foo.get_instance("blahblah")
+    with pytest.raises(KeyError):
+        Foo.get_instance("duplicated")