Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
MaximeVH committed Feb 16, 2024
1 parent 109151e commit 9a96a57
Showing 1 changed file with 11 additions and 11 deletions.
22 changes: 11 additions & 11 deletions README.md
@@ -1,7 +1,7 @@

# EquivalentCircuits.jl

This Julia module allows users to analyse their **electrochemical impedance spectroscopy** (EIS) data using **equivalent electrical circuits**. EquivalentCircuits.jl can be used to either fit the parameters of a given equivalent electrical circuit , or to get recommendations for an appropriate equivalent electrical circuit configuration. The latter is done by conducting an automatic literature search, where the compatibility of impedance measurements with a variety of equivalent circuits from the EIS literature is evaluated. Alternatively, a [gene expression programming](https://en.wikipedia.org/wiki/Gene_expression_programming)-based approach can be used to algorithmically search for compatible circuits.
This Julia module allows users to analyse their **electrochemical impedance spectroscopy** (EIS) data using **equivalent electrical circuits**. EquivalentCircuits.jl can be used to either fit the parameters of a given equivalent electrical circuit or to get recommendations for an appropriate equivalent electrical circuit configuration. The latter is done by conducting an automatic literature search, where the compatibility of impedance measurements with a variety of equivalent circuits from the EIS literature is evaluated. Alternatively, a [gene expression programming](https://en.wikipedia.org/wiki/Gene_expression_programming)-based approach can be used to algorithmically search for compatible circuits.

## Installation
The package can be installed using the package manager.
Expand All @@ -11,7 +11,7 @@ The package can be installed using the package manager.

## Usage
### Circuit notation
Equivalent electrical circuit models are composed of electrical elements, connected in series or in parallel. The four fundamental elements that are most commonly encountered in equivalent electrical circuits, are resistors, capacitors, inductors and constant phase elements. These four elements are represented by the capital letters R, C, L and P, respectively. serially connected elements have dashes between them, wereas parallely connected elements are placed between square brackets and separated by a comma. Finally all the elements in a circuit are numbered. Using these notation rules, the circuit `R1-[C2,R3-[C4,R5]]` corresponds to:
Equivalent electrical circuit models are composed of electrical elements, connected in series or in parallel. The four fundamental elements that are most commonly encountered in equivalent electrical circuits are resistors, capacitors, inductors and constant-phase elements. These four elements are represented by the capital letters R, C, L and P, respectively. serially connected elements have dashes between them, whereas parallelly connected elements are placed between square brackets and separated by a comma. Finally, all the elements in a circuit are numbered. Using these notation rules, the circuit `R1-[C2,R3-[C4,R5]]` corresponds to:

![](example_circuit.png)

Expand All @@ -28,13 +28,13 @@ When an appropriate circuit model is available, the parameters can be fitted to
- `data` : the filepath of the electrochemical impedance measurement data.

Furthermore, there are three optional keyword arguments for increased functionality:
- `x0`: An optional initial parameterset
- `weights`: A vector of equal length as the frequencies. This can be used to attatch more importance to specific areas within the frequency range.
- `x0`: An optional initial parameter set
- `weights`: A vector of equal length as the frequencies. This can be used to attach more importance to specific areas within the frequency range.
- `fixed_params`: A tuple with the indices of the parameters that are to be fixed during the optimisation and the corresponding fixed parameter values.

The data should be provided as a CSV file with three columns: imaginary impedance, real impedance and frequency (see example_measurements.csv).

Lets first take a look at what the çontents of the [example_measurements.csv](https://github.com/MaximeVH/EquivalentCircuits.jl/blob/master/example_measurements.csv) file look like:
Let's first take a look at what the contents of the [example_measurements.csv](https://github.com/MaximeVH/EquivalentCircuits.jl/blob/master/example_measurements.csv) file look like:

```julia
using CSV, DataFrames
Expand All @@ -55,7 +55,7 @@ println(df)

```

Next we can fit the parameters of our example ciruit to the example measurement data as follows:
Next, we can fit the parameters of our example circuit to the example measurement data as follows:
```julia
circuitparams = parameteroptimisation(circuitstring,data)
```
Expand All @@ -69,21 +69,21 @@ frequencies = [0.10, 0.21, 0.43, 0.89, 1.83, 3.79, 7.85, 16.24, 33.60, 69.52, 14
circuitparams = parameteroptimisation(circuitstring,measurements,frequencies)
```
### Circuit literature search
The compatibility of a given set of impedance measurements with circuits from similar applications is evaluated with the `circuit_search(data,domain;kwargs)` function. Users can finetune the search by restricting the complexity and element composition of the returned circuits. The function returns the compatible circuits along with their Digital Object Identifier (DOI) so that users can examine the circuits' other uses to further evaluate its suitability. An overview of the function's inputs is provided below:
The compatibility of a given set of impedance measurements with circuits from similar applications is evaluated with the `circuit_search(data,domain;kwargs)` function. Users can finetune the search by restricting the complexity and element composition of the returned circuits. The function returns the compatible circuits along with their Digital Object Identifier (DOI) so that users can examine the circuits' other uses to further evaluate their suitability. An overview of the function's inputs is provided below:

- `data` : A CSV filepath to the measurements with their frequency information.
- `domain` : The application. The supported applications are: "Animals", "Plants", "Biosensors" , "Batteries", "Fuel_cells" , "Supercapacitors", and "Materials".
- `terminals` : (optional) the circuit components that are to be included in the circuit identification.
- `max_complexity` : a hyperparameter than controls the maximum considered complexity of the circuits.
- `max_complexity` : a hyperparameter that controls the maximum considered complexity of the circuits.

### Circuit fitting
When only the electochemical impedance measurements are available, equivalent electrical circuit recommendations can be also be obtained using the `circuit_evolution(data;kwargs)` function. Details on the algorithm can be found in the [paper](https://ieeexplore.ieee.org/document/9539171). The data can once again be provided as a CSV file's filepath. A variety of keyword arguments can be adjusted to fine-tune the gene expression programming circuit identification procedure.The possible keyword agruments to tune the cirucit identification are:
When only the electrochemical impedance measurements are available, equivalent electrical circuit recommendations can also be obtained using the `circuit_evolution(data;kwargs)` function. Details on the algorithm can be found in the [paper](https://ieeexplore.ieee.org/document/9539171). The data can once again be provided as a CSV file's filepath. A variety of keyword arguments can be adjusted to fine-tune the gene expression programming circuit identification procedure. The possible keyword arguments to tune the cirucit identification are:

- `generations` : the maximum number of algorithm iterations.
- `population_size` : the number of individuals in the population during each iteration.
- `terminals` : the circuit components that are to be included in the circuit identification.
- `cutoff`: a hyperparameter that controls the circuit complexity by removing redundant components. Lower values lead to more simple circuits, however too low values will lead to circuits that no longer fit the measurements well.
- `head` : a hyperparameter than controls the maximum considered complexity of the circuits.
- `head` : a hyperparameter that controls the maximum considered complexity of the circuits.
- `initial_population` : the option to provide an initial population of circuits with which the algorithm starts, this initial population can be either a list of Circuit objects (as loaded with the loadpopulation function) or a custom list of circuits which can either be a list of one or more circuit strings or a list of tuples where each tuple has the circuit string as first value and the parameters as second value.

The defaults values are as follows:
Expand All @@ -109,7 +109,7 @@ Alternatively, this function can also accept the measurements and frequencies as
circuit_evolution(measurements,frequencies,terminals="RC")
```

Next, the file [Circuitlibrary.csv](https://github.com/MaximeVH/EquivalentCircuits.jl/blob/master/Circuitlibrary.csv) contains a collection of various circuit topologies. We can allow the algorithm to start from this circuit collection as initial population as follows:
Next, the file [Circuitlibrary.csv](https://github.com/MaximeVH/EquivalentCircuits.jl/blob/master/Circuitlibrary.csv) contains a collection of various circuit topologies. We can allow the algorithm to start from this circuit collection as the initial population as follows:

```julia
# Load the population from the CSV file, using the loadpopulation function.
Expand Down

0 comments on commit 9a96a57

Please sign in to comment.