Redesign EITForward(mesh, protocol) API

[liubenyuan]

The latest dev branch is working on a redesign (not backward compatible) version of EITForward class. This new design isolate,

1. mesh (including pts: coordinates of nodes, tri: the connection of simplices, perm: permittivity, el_pos: electrode positions, ref: reference node),
2. and the measurement protocol (ex_mat: excitation matrix (Neumann BC only, yet), step: voltage difference electrode, parser: measurement order).

For example,

# forward simulation
fwd = EITForward(mesh, protocol)
v0 = fwd.solve_eit()
v1 = fwd.solve_eit(perm_new, init=True)
# EIT imaging
algo = JAC(mesh, protocol)
ds = algo.solve(v1, v0, normalize=True)

The mesh and protocol can be a dict, or a dataset(#44), if the code block for building these two data structures (mesh, protocol) are intuitive to use, i.e., see the construction code of mesh and protocol in examples.

This new version (maybe 2.0) of pyeit will be release based on these two milestones:

• [x] simple, clean and easy to use API for EIT forward and inverse simulations,
• [ ] large scale Forward simulation using a fine-grained Head/Thorax phantoms.

[DavidMetzIMT]

Great job,

that way the api can be really more clear.

I think using dataclass can definetly bring improvement and we could do some tests on the data directly which and remove the method like check* in the dataclass directly

about the protocol I think only ex_mat and meas_mat (so that multiple type of meas_patttern can be used in future) that way we do not need the meas_pattern method in EITforward () (which shoul only compute fwd results, jac. bp)

I will try to implement both dataclass with corresponding wrapper!

@dataclass
class PyEITMesh
     node
     element
     perm
     el_pos
     ref_el
     ...

@dataclass
class PyEITProtocol
     ex_mat
     meas_mat
     ...

[liubenyuan]

In this way, we may need a wrapper to convert ex_mat, step, and parser to generate a meas_mat, (which is voltage_meter(), or build_meas_pattern()).

About dataset over dictionary. We generate a mesh object from distmesh or using some exist meshes and write a wrapper to generate the mesh_obj. In order to use this mesh dataclass, do we need to redefine these dataclass in fem.py or base.py?

[DavidMetzIMT]

see PR #47

[liubenyuan]

see PR #47

Done, merge to master.

[liubenyuan]

Drop init=True flag #51

[liubenyuan]

88 Inhomogeneous measurement protocol, redefined meas_mat

Previously, meas_mat is a 3-dimensional ndarray which represents the excitation id and the differential pairs [n, m]. What if we want to combine the differential pairs of adjacent (16 elctrodes, 13 measurements per exc) and opposite (16 electrodes, 12 measurements per exc) excitations?

This PR implements a vstacked version os meas_mat. Now meas_mat is a 2-dimensional array, of size n_meas x 3. Each column represents [n, m, exc_id].

The benefit of using this type of measurement matrix is that:

1. it allows inhomogeneous excitation patterns of different number of measurements. Moreover, you could write your own customized measurement [n, m, exc_ids] easily.
2. it allows fast implementation of subtract_row_vectorized and smear_nd and a much cleaner implementation of calculating jac, see the code accordingly.