{"id":13422143,"url":"https://github.com/zehao99/CEIT","last_synced_at":"2025-03-15T10:31:42.412Z","repository":{"id":37682246,"uuid":"276799044","full_name":"zehao99/CEIT","owner":"zehao99","description":"Python Package for EIT(Electric Impedance Tomography)-like problems using Gauss-Newton method.","archived":false,"fork":false,"pushed_at":"2022-12-08T11:41:18.000Z","size":31407,"stargazers_count":13,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-16T11:52:00.282Z","etag":null,"topics":["calculation","eit","fem","inverse-problems","realtime-solver","tomography"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zehao99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-03T03:31:46.000Z","updated_at":"2024-09-03T12:20:48.000Z","dependencies_parsed_at":"2023-01-25T12:45:37.289Z","dependency_job_id":null,"html_url":"https://github.com/zehao99/CEIT","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zehao99%2FCEIT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zehao99%2FCEIT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zehao99%2FCEIT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zehao99%2FCEIT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zehao99","download_url":"https://codeload.github.com/zehao99/CEIT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243719119,"owners_count":20336592,"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":["calculation","eit","fem","inverse-problems","realtime-solver","tomography"],"created_at":"2024-07-30T23:00:37.980Z","updated_at":"2025-03-15T10:31:41.916Z","avatar_url":"https://github.com/zehao99.png","language":"Python","funding_links":[],"categories":["EIT simulation libraries"],"sub_categories":[],"readme":"# CEIT\n\nPython Package for EIT(Electric Impedance Tomography)-like method on detecting capacitance Density Distribution.\n\n## Table of Contents\n- [CEIT](#ceit)\n  - [Table of Contents](#table-of-contents)\n  - [Overview](#overview)\n  - [Installment](#installment)\n  - [Configure the calculation](#configure-the-calculation)\n  - [Quick Start](#quick-start)\n  - [Read Mesh Class](#read-mesh-class)\n    - [1. Initialize a new mesh](#1-initialize-a-new-mesh)\n    - [2. Read from generated mesh cache](#2-read-from-generated-mesh-cache)\n  - [Forward Simulator](#forward-simulator)\n  - [Jacobian Constructor](#jacobian-constructor)\n  - [Realtime Solver](#realtime-solver)\n  - [How to implement your own forward model?](#how-to-implement-your-own-forward-model)\n  - [Cite our work](#cite-our-work)\n\n## Overview\n\nThis python package is designed for solving the tomographic problem concerned with detecting proximity map by a planar conductive sensor.\n\nIt can also be used on other \"weird\" types of EIT-like problem(**different differential equation compared to traditional EIT**), **this package is now focusing on Gauss-Newton solver**. If you are looking into impedance problem specifically, then maybe you want to check out this [package](https://github.com/liubenyuan/pyEIT).\n\nFor more information, please check [my paper](https://ieeexplore.ieee.org/document/9254590).\n\nThe `EFEM` class is written only for this problem, other modules can be reused in any other EIT application.\n\nCEIT provides the ability to generate solver for realtime reconstruction.\nGiven the meshes and electrode positions, CEIT can generate Inverse model for any planar sensor design.\n\n\u003e **KIND REMINDER**: be sure to config the `.gitignore` file, the `.csv` files generated are pretty large...\n\n## Installment\n\nInstall through pip or download the code.\n\n```shell\npip install CEIT\n```\n\nIf you download this code, see `requirements.txt`, one thing to mention is that to accelerate the calculation process, you can use GPU acceleration.\nTo enable this you have to do the following steps.\n\n\u003e 1. Set the `\"device\"` option in `config.json` to `\"gpu\"` \n\u003e 2. Cancel the comment inside function `calculate_FEM_equation()` at the end of file `./MyEIT/efem.py`.\n\u003e 3. cancel the line of `import cupy as cp` in `./MyEIT/efem.py`.\n\u003e 4. Install [`cupy`](https://docs.cupy.dev/en/stable/install.html) package according to your CUDA version, e.g.\n     `\n     python -m pip install cupy-cuda101\n     `, check the installation guide [here](https://docs.cupy.dev/en/stable/install.html#install-cupy).\n\n**Currently this package only work on 2D meshes.**\n\n## Configure the calculation\n\nYou should configure the `config.json` file before using this package.\n\nPlease put the `config.json` file in the same folder as `\\MyEIT`.\n\nA `.fem` file is needed for initializing the whole process. You can get one by using CAD software.\n\nAlso, you have to decide your electrode center positions, and your radius of the electrode.\nInside this package, the electrode is square shaped for which the radius means **half width** of the square.\nBe sure to set all the fields.\n\nFor Examples see `config.json` file.\n\n| Parameter Name | Type | Description |\n| :----: | :----: |:----:|\n|`\"signal_frequency\"`| `Number` | Frequency of your input signal unit: Hz |\n|`\"resistance\"`|`Number`| The resistance of the coductive sheet unit: \u0026Omega;/sq \n| `\"mesh_filename\"` | `String` | File name for your mesh file |\n| `\"folder_name\"` | `String` | Specify the folder you wish to put your mesh file and all the cache files.|\n| `\"optimize_node_num\"`| `Boolean` | Whether shuffle node number at initializing mesh |\n| `\"shuffle_element\"` | `Boolean` | Whether shuffle elemets at initializing mesh |\n| `\"electrode_centers\"` | `Array` | Center of electrodes on perimeter THE UNIT IS **mm** |\n| `\"electrode_radius\"`| `Number` | In this package electrodes are treated as square shaped, this parameter is half of its side length.\n| `\"variable_change_for_JAC\"` |`Number`| variable change on every single element when calculating the Jacobian matrix.|\n| `\"detection_bound\"`| `Number` | Specify the detection boundary size please keep its unit identical to the `\"unit\"` property|\n| `\"calc_from\"`| `Number` | Set starting electrode for Jacobian calculation, for multiple instances compute usage.\n| `\"calc_end\"` | `Number` | Set ending electrode for Jacobian calculation, for multiple instances compute usage.\n| `\"regularization_coeff\"` | `Number` | This parameter is used in regularization equation of reconstruction, **you will have to optimize it**.\n| `\"device\"` |  `String` | Calculation device, only `\"cpu\"` or `\"gpu\"` is accepted, if you choose `\"cpu\"` please follow the instructions in the previous paragraph.|\n| `\"sensor_param_unit\"` | `String` | Unit for the input sensor parameters above. Only `\"mm\"` or `\"SI\"` is accepted, **they will all be transferred into SI unit**.|\n| `\"mesh_unit\"`| `String` | the length unit of your mesh file there are 4 options `mm` `cm` `m` `inch`.\n| `\"reconstruction_mode\"` |`String`| DEPRECATED ITEM keep this to `\"n\"`|\n| `\"overall_origin_variable\"` |`Number`| DEPRECATED ITEM keep this to `0`|\n\n## Quick Start\n\nThere are some samples in the folder.\n\n* `Example_01` Initilize Mesh\n* `Example_02` Forward Calculation\n* `Example_03` Generate jacobian matrix\n* `Example_04` Realtime solver\n\n\n## Read Mesh Class\n\nAll the mesh initializer is put in `MyEIT.ReadMesh`.\n\nNow the reader only work with `.fem` files generated by Altair HyperMesh and the standard calculation unit of length inside this package is METER.\n\n### 1. Initialize a new mesh\nFirst you should finish configuring your `config.json` file according to the previous paragraph.\n\nYour mesh length unit should be corresponding to `\"mesh_unit\"` option inside config.json.\n\nThe initializer can accept 4 kinds of units `mm | cm | m | inch`.\n\nThen on the first time running of a new mesh, call `init_mesh()` function to initialize mesh.\n\nWhen initializing, the class will automatically clear out duplicated mesh and you can decide whether it \nshould shuffle the mesh number or not.\n\nAfter initializing, in the folder you specified before, the method would generate a `Mesh_Cache_Node.csv` \nfile and a `Mesh_Cache_Element.csv` file.\n\n```python\nfrom CEIT.readmesh import init_mesh\n\ninit_mesh(draw=True)\n```\n\n### 2. Read from generated mesh cache\n\nAfter initializing the mesh, you can quickly read from the cache file.\n\nAll the config value inside the json file which is related to length is in `\"sensor_param_unit\"` only `\"mm\"` and `\"SI\"` is supported\n\nClass `read_mesh_from_csv` provides function to read mesh from csv file.\nThe default calculation unit inside CEIT is **SI** units, if your mesh is in **mm** unit, please set in `config.json` file.\n\n**You need to call `return_mesh()` method to get the mesh object and electrode information.**\n\n```python\nfrom CEIT.readmesh import read_mesh_from_csv\n\nread_mesh = read_mesh_from_csv()\nmesh_obj,_,_,_ = read_mesh.return_mesh()\n```\n\n## Forward Simulator\n\nThe forward calculator is used Finite Element Method to calculate potential distribution on the surface.\n\nFirst instantiate the class after reading the mesh file.\n```python\nfrom CEIT.EFEM import EFEM\n\nfwd_model = EFEM()\n```\n\nThe initializer will automatically prepare the object for calculation, now you have a fully functioning forward solver.\n\nThere are several functions provided by this object you can call to change variable value and do calculation.\n\n|function Name|Description|\n|:----:|:----:|\n|`EFEM.calculation(electrode_input)`|Forward calculation on given input electrode selection **You have to call this to do the calculation**|\n|`EFEM.plot_potential_map(ax)`|Plot the current forward result, default is `0` before calling `calculation()`|\n|`EFEM.plot_current_variable(ax)`|Plot the given input condition|\n|`EFEM.change_variable_elementwise(element_list, variable_list)`|Change variable density on selected elements|\n|`EFEM.change_variable_geometry(center, radius, value, shape)`|**Assign** variable density on elements inside a certain geometry (square or circle) to the given value|\n|`EFEM.change_add_variable_geometry(center, radius, value, shape)`|**Add** the given variable density on elements inside a certain geometry|\n|`EFEM.change_conductivity(element_list, resistance_list)`|Change conductivity on certain elements|\n|`EFEM.reset_variable(overall_variable)`|Set variable density on all elements to `overall_variable`|\n\n## Jacobian Constructor\n\nThe `EJAC` class provides the function of doing jacobian calculation.\n\nFirst instantiate the class, this class doesn't require creating the `EFEM` class, it will initialize it internally.\nHowever, you have to get the mesh and pass it into the initializer\n```python\nfrom CEIT.EJAC import EJAC\n\njac_calc = EJAC()\njac_calc.JAC_calculation()\n```\n\nIf you had set the value `\"is_first_JAC_calculation\"` inside `config.json` file to `true`, then, if you call method `EJAC.JAC_calculation()`\n, it will start calculating the jacobianmatrix starting from electrode `\"calc_from\"` to `\"calc_end\"`.\nThis allows you to calculate the jacobian matrix on different machines and then combine them together.\nAfter one iteration (an electrode input condition), the function saves JAC matrix to cache file `JAC_cache.npy`.\n\n**If the calculation is completed make sure you change the `\"is_first_JAC_calculation\"` property to `false`, so it won't calculate unexpectedly.**\n\n**This calculation takes a lot of time so please make sure everything's right before starting.**\n\nThis class also provide some methods for you to reconstruct actual EIT data.\n\n|Function Name|Description|\n|:----:|:----:|\n|`EJAC.JAC_calculation()`| Calculate and return JAC Matrix, Auto Save to File on every iteration|\n|`EJAC.eit_solve(self, detect_potential, lmbda)`| Solve inverse problems base on the initial amplitude output (with no object above) generated by simulation **This is for simulation**|\n|`EJAC.eit_solve_4electrodes()`| Solving 4 electrode condition. There are also functions for 8 electrodes|\n|`EJAC.eit_solve_delta_V()`| Reconstruct based on the given amplitude *change* **This is for testing, use solver for realtime calculation**|\n|`EJAC.save_inv_matrix(lmbda)`| set up inverse matrix for realtime solver with regularization parameter `lmbda`|\n|`EJAC.show_JAC()`| Visualize jacobian matrix with color map|\nTo do more with the package, Please read the comment inside `ejac.py`.\n\n## Realtime Solver\n\nThe `Solver` class provides the function of realtime reconstructing data fed in to the `Solver.solve()` function.\n`Solver` class only has one method `Solver.solve()`.\n\nAn example\n```python\nfrom CEIT.Solver import Solver\nimport numpy as np\n\nsolver = Solver()\ndelta_v = np.random.rand(240)\nsolver.solve(delta_v)\n```\n\nIf you generated another Jacobian matrix, you can call the function `reinitialize_solver()` contained in the `MyEIT.solver` module to refresh your `inv_mat.npy` file.\n\n```python\nfrom CEIT.Solver import reinitialize_solver\n\nreinitialize_solver()\n```\n\n## How to implement your own forward model?\n\nFor typical 2D EIT problems, this package can handle all the requirements from interpreting `.fem` mesh file, assigning electrode position, generating JAC matrix to solving the problem with ease of use.\n\nWith different differential equation, the FEM model is almost the same, but the core simulation algorithm has to be edited.\n\nCheck the `FEMBasic` class and `EFEM` class, `FEMBasic` class is an abstract class whose `my_solver` function is an abstract method.\nOverride this method to get your own forward simulator.\n\n## Cite our work\n\nThis package is used in our paper presented on IECON 2020 conference, if you find this package helpful, please cite our work.\n\n```\n@INPROCEEDINGS{\n  9254590,\n  author={Z. {Li} and S. {Yoshimoto} and A. {Yamamoto}},\n  booktitle={IECON 2020 The 46th Annual Conference of the IEEE Industrial Electronics Society}, \n  title={Tomographic Approach for Proximity Imaging using Conductive Sheet}, \n  year={2020},\n  volume={},\n  number={},\n  pages={748-753},\n  keywords={Tomography;proximity imaging;haptics;robot-skin},\n  doi={10.1109/IECON43393.2020.9254590},\n  ISSN={2577-1647},\n  month={Oct},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzehao99%2FCEIT","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzehao99%2FCEIT","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzehao99%2FCEIT/lists"}