[S0063] Create a custom macro component

Multiple circuit components created in the circuit editor can be grouped into a single circuit block and register it as a macro component (sub-circuit) in the editor's library.
Macro components registered in the library are saved on a per-user basis and can be reused in other analyses.
By converting frequently used or complex circuit configurations into a macro component, schematics can be simplified and reused across multiple projects.
This script registers an existing circuit as a macro component.

Preconditions

• One or more study containing a circuit has been created.
• The circuit has been created and components to be macro has been created.
  This script runs on the circuit of the active study in the project tree.
• At least one external terminal required for creating the macro has been placed.

Script Function

• Check if one or more external terminals are placed on the circuit.
  If no external terminals exist, treat this as an error.
• Collect the names of all components on the circuit.
• Create a macro component.
  Create a macro component that includes all components on the circuit.
  The macro component is saved to the circuit editor's library.
  The "SubCircuit" folder represents the top-level location for storing custom macro components.

# Copyright (c) 2026 JSOL CORPORATION
#
# This script is released under the MIT License.
# See the full license text at:
# https://www.jmag-international.com/scriptlibrary/jmag_script_library_mit/

app = designer.GetApplication()

def hasExternalTerminal(circuit):
    """Check if there are external terminals in the circuit."""
    for i in range(circuit.NumInstances()):
        instance = circuit.GetComponentInstance(i)
        typeName = instance.GetScriptTypeName()
        if typeName in (u"LeftExternalTerminal", u"RightExternalTerminal"):
            return True
    return False

def getComponentNames(circuit):
    """Retrieve names of all circuit components."""
    componentNames = []
    for i in range(circuit.NumComponents()):
        component = circuit.GetComponent(i)
        componentNames.append(component.GetName())
    return componentNames

def createMacro(circuit, componentNames, param):
    """Create a macro component from specified circuit component names."""
    macro = circuit.CreateMacro(param[u"title"])
    for componentName in componentNames:
        macro.AddInstance(componentName)
    macro.SetDescription(param[u"description"])
    macro.SetFolder(u"SubCircuit")
    macro.Create()

def main():
    study = app.GetCurrentStudy()
    circuit = study.GetCircuit()
    if not hasExternalTerminal(circuit):
        print(u"Include at least one left or right external terminal to create a macro component.")
        return
    componentNames = getComponentNames(circuit)
    macroParam = {
        u"title" : u"MacroElem",
        u"description" : u"Macro element T1Set"
    }
    createMacro(circuit, componentNames, macroParam)

main()

Download Python source code