Update readme and clean up

README.rst

@@ -1,131 +1,105 @@
 Material database for power electronic usage
 ===============================================
 
-The main purpose of the material database is to provide various materials for FEM simulations or other calculations in which material data from data sheets or own measurements are required.
-
-Possible application scenarios:
-
-* FEM Magnetics Toolbox (`FEMMT <https://github.com/upb-lea/FEM_Magnetics_Toolbox>`__) loads the permeability or the conductivity of the core from the database, depending on the material.
-* Graphical user interface (GUI) in FEMMT can compare properties of the material stored in material database.
-
-
-Overview features
+The materialdatabase mainly contains complex magnetic and dielectric data of soft-magnetic ferrite materials under sinusoidal excitation.
+Typical target applications of the provided material data are magnetic components in power electronic converters operated at switching frequencies reaching from 100 kHz to 3 MHz.
+The database allows to compare materials and measurement setups, to work with fit functions (e.g., Steinmetz), and features data export as interpolation grids.
+FEM solvers like Comsol can directly import these interpolation grids and incorporate the data in frequency-domain simulations.
+The amplitude-dependency of the complex permeability is then typically modeled via local linearization (e.g., based on Newton iterations).
+The open-source FEM Magnetics Toolbox (`FEMMT <https://github.com/upb-lea/FEM_Magnetics_Toolbox>`__) automatically allows to import material data from this database.
+
+Overview
 -------------------
 
-Usable features
-~~~~~~~~~~~~~~~~~
-
-* Human-readable database based on a .json-file
-    * The database currently contains 19 different ferrite materials as shown in the following table
-        * Datasheet: Digitized plots of the manufacturer datasheet (only for plotting)
-        * FEM-Datasheet: Data for FEM-simulation based on the manufacturer datasheet
-        * TDK_MDT: Data for FEM-simulation based on the magnetic design tool by Epcos TDK
-        * LEA_MTB: Data for FEM-simulation measured by the department of Power Electronics and Electrical Drives at Paderborn University
-        * MagNet: Data for FEM-simulation from the `MagNet <https://mag-net.princeton.edu/>`__ project
+..
+    Key features
+    ~~~~~~~~~~~~~~~~~
+..
+
+* Measurement data is stored in a .csv-files for each combination of material and measurement setup.
+* Data sources:
+    * Complex Permeability:
+        * Datasheet:
+            Data based on datasheet or manufacturer design tool data (e.g., `TDK MDT <https://www.tdk-electronics.tdk.com/de/194550/design-support/tools-fuer-entwickler/ferrite-magnetic>`__ ). The complex permeability is computed from the given loss density and amplitude permeability.
+        * MagNet:
+            Data from the `MagNet <https://mag-net.princeton.edu/>`__ project. The time series data of the sinusoidal measurements is simplified to complex permeability assuming perfectly elliptical hysteresis. For the MagNet data, also DC bias is provided.
+        * LEA MTB (LEA Material Test Bench):
+            Data from measurements at the department of Power Electronics and Electrical Drives at Paderborn University.
+The measurements are taken with a setup employing the `capacitive compensated two-winding method <https://ieeexplore.ieee.org/document/6648460>`__.
+    * Complex Permittivity:
+        * LEA MTB (LEA Material Test Bench):
+            Measurements at the department of Power Electronics and Electrical Drives at Paderborn University. The dielectric measurements are taken with a Wayne Kerr 6515B impedance analyzer on thin silver-plated cuboidal cores.
+* The database currently contains the ferrite materials listed in the following table:
 
 |material_overview|
 
-
-* Input features:
-    * Write magnetic parameters into the database
-        * Amplitude of permeability
-        * Angle of permeability
-        * Power loss density (hysteresis losses)
-        * Magnetic flux density
-        * Magnetic field strength
-
-    * Write electric parameters into the database
-        * Amplitude of permittivity
-        * Angle of permittivity
-        * Power loss density (eddy current losses)
-        * Electric flux density
-        * Electric field strength
-
-    * Write datasheet data into the database
-
-* Output features:
-    * Get the magnetic parameters from the database
-    * Providing permeability and permittivity data for `FEMMT <https://github.com/upb-lea/FEM_Magnetics_Toolbox>`__
-
-* Interpolation of material data (both electric and magnetic parameters)
-
-* GUI features (included in `FEMMT <https://github.com/upb-lea/FEM_Magnetics_Toolbox>`__):
-    * Compare the datasheet values of different ferrite cores (e.g. BH-curves or power-loss curves)
-    * Materials for comparison:
-        * N95
-        * N87
-        * N49
-        * PC200
-        * DMR96A
-
-Planned features (Roadmap for 202x)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* Input features:
-    * Universal function to write data into the database
-
-* Output features:
-    * Get the electric parameters from the database
-    * Extract data from the database as a specific data file (e.g. .csv)
-
-* Plotting features:
-    * Plot the data of a specific ferrite material, e.g. the amplitude of the permeability over the magnetic flux density
-
-* Filter features:
-    * Get all available data for specific filter keys (e.g. temperature, frequency, material etc.)
-    * Filter for some specific value intervals (e.g. 10mT < B-flux < 30mT)
-
 Installation
 ---------------
 
 ::
 
     pip install materialdatabase
 
+Example Data
+------------------------------------
+The data is stored in .csv files:
+
+|material_data|
+
 
-Basic usage and minimal example
+Example Code
 ------------------------------------
 
-Material properties:
+Material properties can be loaded as follows:
 ::
+    mdb_data = mdb.Data()
+    material_name = mdb.Material.N95
 
-    material_db = mdb.MaterialDatabase()
-    materials = material_db.material_list_in_database()
-    initial_u_r_abs = material_db.get_material_property(material_name="N95", property="initial_permeability")
-    core_material_resistivity = material_db.get_material_property(material_name="N95", property="resistivity")
+    permeability = mdb_data.get_complex_permeability(material=material_name,
+                                                     data_source=mdb.DataSource.LEA_MTB,
+                                                     pv_fit_function=mdb.FitFunction.enhancedSteinmetz)
+    print(f"Exemplary complex permeability data: \n {permeability.measurement_data.head()} \n")
 
-.. image:: /docs/source/figures/database_json.png
-   :align: center
+    permittivity = mdb_data.get_complex_permittivity(material=material_name,
+                                                     data_source=mdb.DataSource.LEA_MTB)
+    print(f"Exemplary complex permittivity data: \n {permittivity.measurement_data.head()} \n ")
 
-Interpolated permeability and permittivity data of a Material:
 
+Output:
 ::
+    Exemplary complex permeability data:
+                probe        f       T         b      mu_real     mu_imag  h_offset
+    0  R29.5x19x14.9  59629.0  30.145  0.040125  3955.516035  333.486173         0
+    1  R29.5x19x14.9  58929.0  30.154  0.049834  4050.789996  380.241871         0
+    2  R29.5x19x14.9  58329.0  30.154  0.058502  4138.476021  424.009115         0
+    3  R29.5x19x14.9  57929.0  30.147  0.066572  4239.539939  458.079275         0
+    4  R29.5x19x14.9  57529.0  30.158  0.074332  4303.405675  488.755116         0
 
-    b_ref, mu_r_real, mu_r_imag = material_db.permeability_data_to_pro_file(temperature=25, frequency=150000, material_name = "N95", datatype = "complex_permeability",
-                                          datasource = mdb.MaterialDataSource.ManufacturerDatasheet, parent_directory = "")
+    Exemplary complex permittivity data:
+       probe         f   T      eps_real      eps_imag
+    0   LE2  107760.0  28  95567.710843  36977.344836
+    1   LE2  121546.0  28  93791.671181  35002.540113
+    2   LE2  137096.0  28  92085.767038  33189.049457
+    3   LE2  154635.0  28  90442.389511  31563.885192
+    4   LE2  174418.0  28  88863.933437  30088.808585
+
+
+Detailed examples with material comparisons and data exporting can be found in the "examples" folder.
 
-    epsilon_r, epsilon_phi_deg = material_db.get_permittivity(temperature= 25, frequency=150000, material_name = "N95", datasource = "measurements",
-                                          datatype = mdb.MeasurementDataType.ComplexPermittivity, measurement_setup = "LEA_LK",interpolation_type = "linear")
 
-These function return complex permittivity and permeability for a certain operation point defined by temperature and frequency.
 
-GUI (FEMMT)
--------------------
 
-The materials in database can be compared with help GUI in FEM magnetics toolbox. In database tab of GUI, the loss graphs and B-H curves from the datasheets of up to 5 materials can be compared.
+Usage via FEM Magnetics Toolbox (FEMMT)
+-------------------
 
-FEMMT can be installed using the python pip package manager.
+`FEMMT <https://github.com/upb-lea/FEM_Magnetics_Toolbox>`__ can be installed using the python pip package manager.
 
 ::
 
     pip install femmt
 
-
 For working with the latest version, refer to the `documentation <https://upb-lea.github.io/FEM_Magnetics_Toolbox/intro.html>`__
 
-|gui_database|
-
-|gui_database_loss|
 
 Bug Reports
 --------------
@@ -138,6 +112,5 @@ Changelog
 
 Find the changelog `here <CHANGELOG.md>`__.
 
-.. |gui_database| image:: /docs/source/figures/gui_database.png
-.. |gui_database_loss| image:: /docs/source/figures/gui_database_loss.png
-.. |material_overview| image:: /docs/source/figures/Material_Database_Overview.png
+.. |material_overview| image:: /docs/source/figures/overview.jpg
+.. |material_data| image:: /docs/source/figures/exemplary_N95_permeability_data.jpg