{"id":21500000,"url":"https://github.com/elmercsc/elmer_circuitbuilder","last_synced_at":"2025-08-07T05:24:32.411Z","repository":{"id":57426074,"uuid":"421358530","full_name":"ElmerCSC/elmer_circuitbuilder","owner":"ElmerCSC","description":"Python module for creating the circuit simulation definitions for Elmer FEM ","archived":false,"fork":false,"pushed_at":"2025-04-10T07:50:28.000Z","size":2791,"stargazers_count":11,"open_issues_count":1,"forks_count":8,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-06-27T22:05:36.559Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElmerCSC.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-26T09:17:46.000Z","updated_at":"2025-04-24T09:34:18.000Z","dependencies_parsed_at":"2025-06-27T22:05:40.456Z","dependency_job_id":null,"html_url":"https://github.com/ElmerCSC/elmer_circuitbuilder","commit_stats":{"total_commits":28,"total_committers":3,"mean_commits":9.333333333333334,"dds":0.1428571428571429,"last_synced_commit":"370792ffd07d4be03a8707768c35ad7690470101"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ElmerCSC/elmer_circuitbuilder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElmerCSC%2Felmer_circuitbuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElmerCSC%2Felmer_circuitbuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElmerCSC%2Felmer_circuitbuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElmerCSC%2Felmer_circuitbuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElmerCSC","download_url":"https://codeload.github.com/ElmerCSC/elmer_circuitbuilder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElmerCSC%2Felmer_circuitbuilder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262341618,"owners_count":23296069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T17:20:11.285Z","updated_at":"2025-06-27T22:05:52.725Z","avatar_url":"https://github.com/ElmerCSC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# What is the CircuitBuilder?\nThe Elmer CircuitBuilder is a Python library with components such as ideal sources(V,I), resistors(R), capacitors (C), and inductors (L) \nto streamline the creation of circuit networks and enable circuit-field simulations by building the stiffness and damping matrices needed.\nThe available Finite Element coil models in Elmer's component block are: massive, stranded and foil, in 2D and 3D. \n\nIn this directory you'll find basic examples on how to model coils in Magnetodynamics applications using ElmerFem. \nGlobal sources (e.g., Ideal Voltage and Current Sources) can be added using electrical networks with the help of the elmer_circuitbuilder Python module. \n\n![3D Stranded Closed Coil](readme_figures/TEAM7_current_source.png)\n\n# How to Download the CircuitBuilder\nTo use and take advantage of the models in this directory go to Terminal and enter:\n\n```\n$ pip install elmer-circuitbuilder\n```\n\n# How does Elmer CircuitBuilder work?\nAfter importing all the functions within the library into a fresh Python file (see main_template.py or main.py in each model), you can develop a circuit network \nusing a common two-terminal component approach. \n\nThe steps are simple. The idea is that after following the main.py template on the examples in this directory you'll be able to create\nyour own circuit to model coils with ElmerFEM. The steps are summarized below.\n\nInstructions: \\\n               1) Import the circuit builder library (from elmer_circuitbuilder import *) \\\n               2) Set output file name as a string (e.g output_file = \"string_circuit.definitions\") \\\n               3) Set number of circuits with number_of_circuits(n) (e.g c = number_of_circuits(1)) \\\n               4) Set your ground/reference node in the current circuit c[1].ref_node = pin_number \\\n               5) Select and configure electrical component \\\n                     Resistors (R), Inductors (L), Capacitors (C), Voltage Source (V), Current Source (I)\n                     or FEM Component (ElmerComponent) \n                     Arguments needed for R, L, C, V, I is the same. ElmerComponent takes additional arguments\\\n               6) Add circuit components to circuit c[n].components.append([R1, V1, ElmerFemCoil, ...etc]) \\\n               7) Write circuits generate_elmer_circuits(c, output_file) \\\n               8) Output file must be included in .sif file \n\n##  The CircuitBuilder Template\nThe steps can be easily spotted on the following template\n\n```\n# Imported Libraries:\nimport sys\nfrom elmer_circuitbuilder import *                                                 # STEP 1\n# -------------------------------------------------------------------------------\n\ndef main(argv=None):\n\n    # name output file - do not remove                                             # STEP 2\n    output_file = \"\"\n\n    # initialize circuits: number of circuits - do not remove                      # STEP 3\n    c = number_of_circuits(1)\n\n    # reference/ground node needed - do not remove.                                # STEP 4\n    c[1].ref_node = 1\n\n    # ----------------------- Electrical Network Definition ---------------------  # STEP 5\n\n    # Components\n\n    # Define coil type: massive, stranded, foil\n\n    # Define dimension related features if needed (closed, open)\n\n    # store components in array components = [comp1, comp2,...] - do not remove    # STEP 6\n    c[1].components.append([])                                 \n\n    # ---------------------------------------------------------------------------\n\n    # generate elmer circuit.definitions - do not remove / do not edit             # STEP 7\n    generate_elmer_circuits(c, output_file)                              \n\n    return 0\n\n\nif __name__ == \"__main__\":\n    sys.exit(main() or 0)\n\n```\n\nNote that STEP 8 is not part of the template but rather on the .sif file itself as an include of the .definition file created by the CircuitBuilder\n\n```\nInclude \"\u003cname_of_circuit\u003e.definition\"\n```\n\n##  How to create Components (STEP 5)?\n\nThe components are created as objects I, V, R, L, C and/or, ElmerComponent.\nThe code is documented using Docstrings, hence, it's encouraged to use an IDE. Below you can see how the documentation can be retrieved by hovering over the object on PyCharm:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=readme_figures/elmer_component_doc.png width=\"400\" height=\"150\"\u003e\n  \u003cimg src=readme_figures/volt_doc.png width=\"280\" height=\"150\"\u003e\n\u003c/p\u003e\n\n\n\n##  How does the CircuitBuilder output look like?\n\nThe CircuitBuilder produces a .definition-extension file that includes the basic blocks to use circuit networks in FEM models using ElmerFEM. \n\nThe output file is split into 4 sections: Parameters (1), Circuit matrices (2), Elmer Component Block (3), Elmer Body Force 1 (4) Block. The idea is that the user should only change the values in the Parameters block to modify coil parameters such as resistance, number of turns, etc., according to the coil type used.\n\nSee sample of a CircuitBuilder output file of a single stranded coil (See Component 1) driven by an ideal Current Souce (see Body Force 1):\n\n```\n! -----------------------------------------------------------------------------\n! ElmerFEM Circuit Generated: November 02, 2021\n! -----------------------------------------------------------------------------\n\n! -----------------------------------------------------------------------------\n! Number of Circuits in Model\n! -----------------------------------------------------------------------------\n$ Circuits = 1\n\n! -----------------------------------------------------------------------------\n! Parameters                                                                (1)\n! -----------------------------------------------------------------------------\n\n! General Parameters \n$ I1 = 10\n\n! Parameters in Component 1: Coil1\n$ N_Coil1 = 10\t ! Number of Turns\n$ R_Coil1 = 0.1\t ! Coil Resistance\n$ Ns_Coil1 = 1\t ! Sector/Symmetry Coefficient (e.g. 4 is 1/4 of the domain)\n! -----------------------------------------------------------------------------\n! Matrix Size Declaration and Matrix Initialization                         (2)\n! -----------------------------------------------------------------------------\n$ C.1.variables = 5\n$ C.1.perm = zeros(C.1.variables)\n$ C.1.A = zeros(C.1.variables,C.1.variables)\n$ C.1.B = zeros(C.1.variables,C.1.variables)\n\n! -----------------------------------------------------------------------------\n! Dof/Unknown Vector Definition\n! -----------------------------------------------------------------------------\n$ C.1.name.1 = \"i_I1\"\n$ C.1.name.2 = \"i_component(1)\"\n$ C.1.name.3 = \"v_I1\"\n$ C.1.name.4 = \"v_component(1)\"\n$ C.1.name.5 = \"u_2_circuit_1\"\n\n! -----------------------------------------------------------------------------\n! Source Vector Definition\n! -----------------------------------------------------------------------------\n$ C.1.source.5 = \"I1_Source\"\n\n! -----------------------------------------------------------------------------\n! KCL Equations\n! -----------------------------------------------------------------------------\n$ C.1.B(0,0) = -1\n$ C.1.B(0,1) = 1\n\n! -----------------------------------------------------------------------------\n! KVL Equations\n! -----------------------------------------------------------------------------\n$ C.1.B(1,2) = 1\n$ C.1.B(1,4) = -1\n$ C.1.B(2,3) = -1\n$ C.1.B(2,4) = 1\n\n! -----------------------------------------------------------------------------\n! Component Equations\n! -----------------------------------------------------------------------------\n$ C.1.B(4,0) = 1\n\n\n! -----------------------------------------------------------------------------\n! Additions in SIF file                                                     (3)\n! -----------------------------------------------------------------------------\nComponent 1\n  Name = \"Coil1\"\n  Master Bodies Name = Coil\n  Coil Type = \"Stranded\"\n  Number of Turns = Real $ N_Coil1\n  Resistance = Real $ R_Coil1\n \n  ! Additions for 3D Coil\n  Coil Use W Vector = Logical True\n  W Vector Variable Name = String CoilCurrent e\n  Electrode Area = Real $ Ae_Coil1\nEnd \n\n! -----------------------------------------------------------------------------\n! Sources in SIF                                                            (4)\n! -----------------------------------------------------------------------------\n\nBody Force 1\n  I1_Source = Variable \"time\" \n  \t Real MATC \"I1\"\nEnd\n\n! -----------------------------------------------------------------------------\n! End of Circuit\n! -----------------------------------------------------------------------------\n```\n\nNote that the input current source (I1_Source) under Body Force 1 is a constant value defined in the Parameter's section.\n\n## Time dependent sources\nWe can add appropiate mathematical functions to include time-dependencies. See below how you can include a sinusoidal source by modifying the current source (I1_Source)\n\n```\nBody Force 1\n  I1_Source = Variable \"time\" \n  \t Real MATC \"I1*sin(omega*tx)\"\nEnd\n```\n\n## Harmonic sources\nIf you are working with sinusoidal sources you could benefit from defining your ideal sources as complex valued sources in your CircuitBuilder template\n```\nphase = np.radians(120)\nI1 = I(\"I1\", 2, 1, 1*np.exp(phase*1j))\n```\nThis will output the real and imaginary values necessary to setup the given source\n\n```\nBody Force 1\n  I1_Source re = Real $ re_I1*cos(phase_I1)\n  I1_Source im = Real $ im_I1*sin(phase_I1)\nEnd\n```\n# Coil Models\n\n\n## Massive Conductors \n\nMassive conductors/inductors are simply solid material conductors. The conducting domain $\\Omega_c$ is fully discretized and solved using the magnetodynamics av formulation. Hence, skin effect and proximity effects can be observed. For further information about massive inductors, please see references below.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=readme_figures/massive.png width=\"300\" height=\"150\"\u003e\n\n\u003c/p\u003e\n\n## Homogenization: Stranded, and Foil windings\nIn the case of models that involve multiple conducting filaments (multi-turn coils, stranded coils, etc) or foils/laminations, it is difficult to solve the magnetodynamics problem at a reasonable computational cost. Particularly, at higher frequencies the solution becomes computationally prohibitive. For that reason homogenization methods enable reasonable accuracy in quasi-static problems without the need to fully discretize the conducting domains (i.e. each turn).\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=readme_figures/stranded.png width=\"300\" height=\"150\"\u003e\n    \u003cimg src=readme_figures/foil.png width=\"300\" height=\"150\"\u003e\n\u003c/p\u003e\n\nThe stranded or foil winding can be modeled as a single material as shown below. The stranded model is actually modeled as part of the non-conducting domain, whereas the foil case is modeled as a single conductor just as you would do in the massive case. The difference lies in the formulation, which takes account of the different phenomena occuring in the particular case. For more information about stranded and foil windings see references below.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=readme_figures/homogenized.png width=\"300\" height=\"150\"\u003e\n\u003c/p\u003e\n\n\n\n## What are Closed and Open Coils?\n\nIn 3D we need to make a distinction between open and closed coils depending on the termination of the conductor. To the left you see that the closed coil has only one single (high) terminal, whereas the open coil has two: high and low terminals.\n\nThis distinction is relevant when setting up the circuit network and the finite element model, as modifications will be required to assign these surfaces with the appropiate boundary conditions in the .sif file. \n\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=readme_figures/closed.png width=\"300\" height=\"220\"\u003e  \n      \u003cimg src=readme_figures/open.png width=\"300\" height=\"220\"\u003e\n\u003c/p\u003e\n\nWhen using the CoilSolver, some simplifications are made. In the case of a closed coil automatic cuts are made and no boundary conditions are needed (see image below). \n\n\u003cp align=\"center\"\u003e\n      \u003cimg src=readme_figures/coil_solver_cut.png width=\"300\" height=\"220\"\u003e\n\u003c/p\u003e\n\n\nIf the coil is open, the boundary conditions need to be defined on each terminal of the conductor.\n\n# elmer-elmag/CircuitBuilder directory\n\nThis directory includes general examples for classic coil types in frequency and time domain. \n\nThe 2D directory has two types of examples. First general examples on how to add lumped circuit parameters to be part of a circuit network including a FEM component, and the other examples focus on the setup of massive, stranded and foil windings. \n\n```\n2D/\n├── circuit_examples\n│   ├── current_divider\n│   ├── current_source\n│   ├── voltage_divider\n│   └── voltage_source\n├── foil\n│   ├── harmonic\n│   └── transient\n├── massive\n│   ├── harmonic\n│   └── transient\n└── stranded\n    ├── harmonic\n    └── transient\n```\n\n\nSimilarly, the 3D directory includes general examples on the setup of massive, stranded and foil windings in transient and time harmonic cases.\n```\n3D/\n├── foil\n│   ├── closed\n│   │   ├── harmonic\n│   │   └── transient\n│   └── open\n│       ├── harmonic\n│       └── transient\n├── massive\n│   ├── closed\n│   │   ├── harmonic\n│   │   └── transient\n│   └── open\n│       ├── harmonic\n│       └── transient\n└── stranded\n    ├── closed\n    │   ├── harmonic\n    │   └── transient\n    └── open\n        ├── harmonic\n        └── transient\n\n```\n# References\nFor information about massive, stranded and foil coil types:\n\n\u003cp\u003ePatrick Dular, and Christophe Geuzaine. \n\u003cA HREF=\"https://ieeexplore.ieee.org/abstract/document/996165/\"\u003e\nSpatially dependent global quantities associated with 2d and 3d \u0026magnetic vector potential formulations for foil winding modeling\u003c/A\u003e. \nIEEE trans. magn., 38(2):633–636, March 2002. \u003c/p\u003e\n\natrick Dular, F. Henrotte, and W. Legros.\n \u003cA HREF=\"https://ieeexplore.ieee.org/abstract/document/767310\"\u003e\n A general and natural method to define circuit relations associated with magnetic vector potential formulations \u003c/A\u003e. \n IEEE trans. magn., 35(3):1630–1633, May 1999.\n\nPatrick Dular, Nelson Sadowski, J.P.A. Bastos, and Willy Legros. \u003cA HREF=\"https://ieeexplore.ieee.org/abstract/document/877746\"\u003e\nDual complete procedures to take stranded inductors into account in magnetic vector potential formulations\u003c/A\u003e. \nIEEE trans. magn., 36(4):1600–1605, July 2000.\n\nH. D. Gersem and K. Hameyer. \n\u003cA HREF=\"https://ieeexplore.ieee.org/abstract/document/952629\"\u003e\nA finite element model for foil winding simulation\u003c/A\u003e. \nIEEE trans. magn., 37(5):3427–3432, September 2001.\n\nThe module to couple and solve circuit-field problems is the CircuitAndDynamics\nModule. This module needs the stiffness and damping matrix definitions, for which the CircuitBuilder was created. For more information about the CircuitAndDynamics module:\n\u003cp\u003e\n\u003cA HREF=\"http://www.nic.funet.fi/pub/sci/physics/elmer/doc/ElmerModelsManual.pdf#page=128\"\u003e\nCircuitAndDynamics Module Documentation \u003c/A\u003e\n\u003c/p\u003e\n\nIf you use the CircuitAndDynamics module or the CircuitBuilder, please don't forget to cite the following references:\n\nEelis Takala, Evren Yurtesen, Jan Westerholm, Juha Ruokolainen, and Tommi Peussa. \u003cA HREF=\"https://www.tandfonline.com/doi/pdf/10.1080/02726343.2016.1187107?casa_token=XTTKx7uW-RYAAAAA:xO33zf8Rwi7UccLiGx9ZjY2GaCRPFHHxRXbY-oQ1n8f54vJdkrNu4J0EvZJL4zQ8E-1zHVgx9cS3zQ\"\u003eUsing reduced support to enhance parallel strong scalability in 3d finite element magnetic vector potential formulations with circuit equations\u003c/A\u003e. Electromagnetics, 36(6):400–408, August 2016.\n\nEelis Takala, Evren Yurtesen, Jan Westerholm, Juha Ruokolainen, and Peter Råback. \u003cA HREF=\"https://www.tandfonline.com/doi/pdf/10.1080/02726343.2016.1151616?casa_token=LQoOG9VNPsoAAAAA:OkFQpOERLVG9p14lAjhPtJinnoXdIFc6LgHk2ax411KZqqJPlQVfLxFUndwMCj9Mze5nTneC5sCFeA\"\u003eParallel simulations of inductive components with elmer finite element software in cluster environments\u003c/A\u003e. Electromagnetics, 36(3):167–185, April 2016.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felmercsc%2Felmer_circuitbuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felmercsc%2Felmer_circuitbuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felmercsc%2Felmer_circuitbuilder/lists"}