From 1c1c517554e9914f576fbe26bc113b4dcfdc24b1 Mon Sep 17 00:00:00 2001 From: gituser789 <62549000+gituser789@users.noreply.github.com> Date: Fri, 3 May 2024 13:02:37 +0200 Subject: [PATCH] restructure readme file --- README.rst | 118 +---------------------- docs/source/intro.rst | 1 + docs/source/introduction.rst | 47 +-------- docs/source/readme.rst | 179 +++++++++++++++++++++++++++++++++++ 4 files changed, 186 insertions(+), 159 deletions(-) create mode 100644 docs/source/readme.rst diff --git a/README.rst b/README.rst index df49de18..5f01bb08 100644 --- a/README.rst +++ b/README.rst @@ -1,117 +1 @@ -FEM Magnetics Toolbox (FEMMT) -============================= - -This README only provides a short overview. For more information please have a look at the detailed documentation `here `__. - -Python toolbox to generate preconfigured figures for FEM simulation tools in power electronics. - -The toolbox contains two parts, a reluctance module and a FEM module. - -* The reluctance module is for pre-calculations -* The FEM module is for detailed calculations - -The toolbox is accessible via python code or a graphical user interface -(GUI), which current development status is experimental. - -|image0| - -Functionality examples - -* work with pre-defined standard core structures -* work with pre-defined litz wires -* use python to perform parameter sweeps, e.g.perform several automated simulations of different air gap sizes -* read the results automated with python from the FEM simulation tool -* run a thermal simulation to see the temperatures, once the magnetoquasistatic simulation has finished - -**Note: Alpha Version!** - -* GUI is experimental, -* reluctance module is currently working for a single optimization example and not fully implemented yet. - -Documentation -------------------- -Please have a look at the `documentation `__. You will find tutorials and a function description. - -Installation ---------------- - -To run FEMMT python (version 3.10 or above) and onelab is needed. - -ONELAB installation -~~~~~~~~~~~~~~~~~~~~~~~ - -- Go to https://onelab.info/ -- Download the Desktop Version for your OS (Windows, Linux or macOS) -- Unpack the software and remember the file path. This will be needed - later when installing FEMMT. - -Install FEMMT -~~~~~~~~~~~~~~~~~ - -FEMMT can be installed using the python pip package manager. -This is the stable release version (recommended). - -:: - - pip install femmt - -For working with the latest version, refer to the `documentation `__. - -Minimal example ------------------- - -This toolbox is able to build a complete FEM simulation from simple -Python code. The following figure shows the Python code on the left and -the corresponding FEM simulation on the right. |image1| - -To run a minimal example please have a look at the `examples `__. - -GUI (Experimental) -------------------- - -There is a first preview for a GUI. Installing this is a bit cumbersome -at first, but will be simplified in the future: - -* Download the complete repository via ``Code`` -> ``Download ZIP`` and unpack it. -* install the development version of femmt as described above -* run python ``downloads/path-to_femmt/femmt/gui/femmt_gui.py`` - -Please note, the GUI is experimental. - -|image2| - -Bug Reports --------------- - -Please use the issues report button within github to report bugs. - -Contributing ---------------- - -Pull requests are welcome. For major changes, please open an issue first -to discuss what you would like to change. For contributing, please refer -to this `section `__. - -Changelog ------------- - -Find the changelog `here `__ - -License ----------- - -`GPLv3 `__ - -History and project status ------------------------------- - -This project was initially written in matlab using FEMM simulation tool. -It became clear that the project was no longer a small project. The -project should be completely rewritten, because many new complex levels -have been added. To place the project in the open source world, the -programming language python is used. - -.. |image0| image:: docs/images/femmt.png -.. |image1| image:: docs/images/FEMMT_Screenshot.png -.. |image2| image:: docs/images/femmt_gui_definition.png -.. |image3| image:: docs/images/counting_arrow_system.png +.. include:: docs/source/introduction.rst \ No newline at end of file diff --git a/docs/source/intro.rst b/docs/source/intro.rst index e930f6c0..e97ec5b0 100644 --- a/docs/source/intro.rst +++ b/docs/source/intro.rst @@ -1,5 +1,6 @@ .. sectnum:: +.. include:: readme.rst .. include:: introduction.rst diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 59acf163..24d62324 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -1,44 +1,7 @@ -FEM Magnetics Toolbox (FEMMT) -============================= -Python toolbox to generate preconfigured figures for FEM simulation -tools in power electronics. - -The toolbox contains two parts, a reluctance module and a FEM module. - -* The reluctance module is for pre-calculations -* The FEM module is for detailed calculations - -Installation ---------------- - -To run FEMMT, python (version 3.8 or above) and onelab is needed. - -ONELAB installation -~~~~~~~~~~~~~~~~~~~~~~~ - -- Go to https://onelab.info/ -- Download the Desktop Version for your OS (Windows, Linux or macOS) -- Unpack the software and remember the file path. This will be needed - later when installing FEMMT. - -Install FEMMT -~~~~~~~~~~~~~~~~~ - -FEMMT can be installed using the python pip package manager. -Either a release version can be installed using pip or a development version by downloading this repository. - -FEMMT release version (recommended) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This installs the stable release version. - -:: - - pip install femmt FEMMT development version (for developers only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------------------------------ This is the latest development version with the latest features. Note: You may need to install `git `__. @@ -70,8 +33,8 @@ This toolbox is able to build a complete FEM simulation from simple Python code. The following figure shows the Python code on the left and the corresponding FEM simulation on the right. |image_femmt_screenshot| -Code examples can be found in this `example file `__. This file is updated -regulary. +Code examples can be found in this `example folder `__. These files are updated +regularly. Basics ~~~~~~~~~~ @@ -87,8 +50,8 @@ divided into the following steps: 5. set conductor parameters (litz/solid wire), 6. start the frequency domain simulation by specifying the given frequencies, currents, and phases, and start the time domain simulation by specifying the given currents, and time parameters. -Please have a look at the `basic_example `__ for frequency domain simulation, and -at the `basic_example `__ for time domain simulation. +Please have a look at the `basic_inductor example `__ for frequency domain simulation, and +at the `basic_inductor_time_domain example `__ for time domain simulation. The examples contain among other things: diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 00000000..1aabe84d --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1,179 @@ +FEM Magnetics Toolbox (FEMMT) +============================= + +This README only provides a short overview. For more information please have a look at the detailed documentation `here `__. + +Python toolbox to generate preconfigured figures for FEM simulation tools in power electronics. + +The toolbox is accessible via python code or a graphical user interface +(GUI), which current development status is experimental. + + +Overview features +------------------- + +Stable features +~~~~~~~~~~~~~~~~~ + +* Component features: + * 2D axi-symmetric cylindrical simplification + * `Inductor `__, `2-winding transformer `__, `n-winding transformer `__ + * Arbitrary (distributed) air gap positioning in center leg + * Variety of winding interleaving schemes + * Special geometries: + * `Center tapped transformer `__ + * `Magnetic shunt `__ (transformer with integrated inductor) + * `Stacked core `__ (transformer with integrated inductor) + * Round litz wire + * Round and rectangular solid wires + * Different winding schemes (hexagonal, left/right, top/down, ...) + * Parallel connection of solid wires + * Insulation distances (winding2core, winding2winding) + * Many `examples `__. to learn and understand FEMMT + * Databases + * Litz wire database + * Core geometry database + * Conductor materials: temperature curves + * Ferrit materials: permeability / permittivity `material database `__ (datasheets and own measurements) + +* Solver features: + * Implemented using `ONELAB `__ + * Current excitation + * Frequency domain solver + * Litz wire loss model for proximity and skin effect (Niyomsatian et al.: Frequency-domain homogenization for impedance characterization of litz-wire transformers in 2-D finite element models) + * Core loss calculation for real materials (data from material database) + * Amplitude dependent loss angle (Local resolution of complex permeability) + * Equivalent permittivity data for eddy current calculations + * Effect of dimensional resonance is considered + * Thermal solver + * Thermal conduction (Poisson equation) + * Fixed temperature and isolation boundary conditions + * Verified model for potted core + +* Pre/Post processing: + * Linear eddy current analysis via input current based FFT + * Pre-visualization of ferrite material (measurement) data interpolation + * Field visualization in gmsh GUI (magnetic flux density, eddy current losses, ...) + * Inductance matrix for n-winding transformer + * Transformer equivalent diagrams for 2- and 3-winding transformer + +* Optimization: + * Parallel computing to speed up simulations (no cpu core limitation) + * Examples for Pareto optimization to adapt to your own optimization problem + + +Experimental features (under development) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Component features: + * Reluctance module is currently working for a single optimization example and not fully implemented yet. +* Solver features: + * Time domain solver +* Optimization: + * Advanced optimization algorithms by connecting to `optuna `__ +* GUI: + * Experimental in general + +Planned features (Roadmap for 202x) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Solver features: + * Core loss calculation from non-sinusoidal flux + * Local temperature dependency (currently only lumped temperature assignment, e.g. general temperature for all windings) + +Not supported features +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Not supported component features: + * Toroidal core + +* Not supported solver features: + * Voltage excitation + + +Documentation +------------------- +Please have a look at the `documentation `__. You will find tutorials and a function description. + +Installation +--------------- + +To run FEMMT python (version 3.10 or above) and onelab is needed. + +ONELAB installation +~~~~~~~~~~~~~~~~~~~~~~~ + +- Go to https://onelab.info/ +- Download the Desktop Version for your OS (Windows, Linux or macOS) +- Unpack the software and remember the file path. This will be needed + later when installing FEMMT. + +Install FEMMT +~~~~~~~~~~~~~~~~~ + +FEMMT can be installed using the python pip package manager. +This is the stable release version (recommended). + +:: + + pip install femmt + +For working with the latest version, refer to the `documentation `__. + +Minimal example +------------------ + +This toolbox is able to build a complete FEM simulation from simple +Python code. The following figure shows the Python code on the left and +the corresponding FEM simulation on the right. |FEMMT_Screenshot| + +To run a minimal example please have a look at the `examples `__. + +GUI (Experimental) +------------------- + +There is a first preview for a GUI. Installing this is a bit cumbersome +at first, but will be simplified in the future: + +* Download the complete repository via ``Code`` -> ``Download ZIP`` and unpack it. +* Or clone the repository +* Install the development version of femmt using ``pip install -e .`` +* Run python ``.../path-to_femmt/femmt/gui/femmt_gui.py`` + +Please note, the GUI is experimental. + +|femmt_gui_definition| + +Bug Reports +-------------- + +Please use the issues report button within github to report bugs. + +Contributing +--------------- + +Pull requests are welcome. For major changes, please open an issue first +to discuss what you would like to change. For contributing, please refer +to this `section `__. + +Changelog +------------ + +Find the changelog `here `__. + +License +---------- + +`GPLv3 `__ + +History and project status +------------------------------ + +This project was initially written in matlab using FEMM simulation tool. +It became clear that the project was no longer a small project. The +project should be completely rewritten, because many new complex levels +have been added. To place the project in the open source world, the +programming language python is used. + +.. |femmt| image:: ../images/femmt.png +.. |FEMMT_Screenshot| image:: ../images/FEMMT_Screenshot.png +.. |femmt_gui_definition| image:: ../images/femmt_gui_definition.png +.. |counting_arrow_system| image:: ../images/counting_arrow_system.png