easy-biologic 0.4.0

Controller class for communicating with BioLogic devices.

Easy Biologic

A library allowing easy control over BioLogic devices. High and low level control over Biologic devices are available. Low level control is included in the lib subpackage, while high level control is available in the main module.

Install with python -m pip install easy-biologic

High Level API

There are two high level API modules containing three classes, and two convenience modules.

Biologic Device

Represents an instance of a Biologic Device.

Methods

• BiologicDevice( address, timeout = 5 ): Creates a new Biologic Device representing the device conencted at address.

• connect( bin_file, xlx_file ): Connects to the device, loading the bin and xlx file if provided.

• disconnect(): Disconnects from the device.

• is_connected(): Whether the device is connected or not.

• load_technique( ch, technique, params, index = 0, last = True, types = none ): Loads a technique onto the given device channel.

• load_techniques( ch, techniques, parameters, types = None ): Loads a series of techniques onto the given device channel.

• update_parameters( ch, technique, parameters, index = 0, types = None ): Update the parameters of the given technqiue on the specified device channel.

• start_channel( ch ): Starts the given channel.

• start_channels( chs = None ): Starts multiple channels.

• stop_channel( ch ): Stops the given channel.

• stop_channels( chs = None ): Stops the given channels.

• channel_info( ch ): Returns information about the given channel.

• channel_configuration( ch ): Returns configuration information of the channel.

• set_channel_configuration( ch, mode, conneciton ): Sets the channel's hardware configuration.

• get_values( ch ): Returns current values of the given channel.

• get_data( ch ): Returns buffered data of the given channel.

Properties

• address: Connection address of the device.
• idn: ID of the device.
• kind: Device model.
• info: DeviceInfo structure.
• plugged: List of available channels.
• channels: List of ChannelInfo structures.
• hardware_configuration: Dictionary of HardwareConfiguration for each channel.
• techniques: List of TechParams loaded on each channel.

Biologic Program

Abstract Class Represents a program to be run on a device.

Methods

• BiologicProgram( device, params, channels = None, autoconnect = True, barrier = None, stop_event = None, threaded = False ): Creates a new program.

• channel_state( channels = None ): Returns the state of the channels.

• on_data( callback, index = None ): Registers a callback function to run when data is collected.

• run(): Runs the program.

• stop(): Sets the stop event flag.

• save_data( file, append = False, by_channel = False ): Saves data to the given file.

• sync(): Waits for barrier, if set.

• _connect(): Connects to the device

Properties

• device: BiologicDevice.
  
• params: Passed in parameters.
  
• channels: Device channels.
  
• autoconnect: Whether connection to the device should be automatic or + not.
  
• barrier: A threading.Barrier to use for channel syncronization. [See ProgramRummer]
  
• field_titles: Column names for saving data.
  
• data: Data collected during the program.
  
• status: Status of the program.
  
• fields: Data fields teh program returns.
  
• technqiues: List of techniques the program uses.

Program Runner

Represents a program to be run on a device channel.

Methods

• ProgramRunner( programs, sync = False ): Creates a new program runner.

• start(): Runs the programs.

• wait(): Wait for all threads to finish.

• stop(): Sets stop event.

Properties

• threads: List of threads for each program.
  
• sync: Whether to sync the threads or not.

Base Programs

Contains basic implementations of BiologicPrograms.

OCV

Params

• time: Run time in seconds.

• time_interval: Maximum time between readings. [Default: 1]

• voltage_interval: Maximum interval between voltage readings. [Default: 0.01]

CA

Params

• voltages: List of voltages.

• durations: List of times in seconds.

• vs_initial: If step is vs. initial or previous. [Default: False]

• time_interval: Maximum time interval between points. [Default: 1]

• current_interval: Maximum current change between points. [Default: 0.001]

• current_range: Current range. Use ec_lib.IRange. [Default: IRange.m10 ]

Methods

• update_voltage( voltages, durations = None, vs_initial = None ): Updates the voltage.

CALimit

Params

• voltages: List of voltages.

• durations: List of times in seconds.

• vs_initial: If step is vs. initial or previous. [Default: False]

• time_interval: Maximum time interval between points. [Default: 1]

• current_interval: Maximum current change between points. [Default: 0.001]

• current_range: Current range. Use ec_lib.IRange. [Default: IRange.m10 ]

Methods

• update_voltage( voltages, durations = None, vs_initial = None ): Updates the voltage.

PEIS

Params

• voltage: Initial potential in Volts.

• amplitude_voltage: Sinus amplitude in Volts.

• initial_frequency: Initial frequency in Hertz.

• final_frequency: Final frequency in Hertz.

• frequency_number: Number of frequencies.

• duration: Overall duration in seconds.

• vs_initial: If step is vs. initial or previous. [Default: False]

• time_interval: Maximum time interval between points in seconds. [Default: 1]

• current_interval: Maximum time interval between points in Amps. [Default: 0.001]

• sweep: Defines whether the spacing between frequencies is logarithmic ('log') or linear ('lin'). [Default: 'log']

• repeat: Number of times to repeat the measurement and average the values for each frequency. [Default: 1]

• correction: Drift correction. [Default: False]

• wait: Adds a delay before the measurement at each frequency. The delay is expressed as a fraction of the period. [Default: 0]

GEIS

Performs a Galvanostatic Electrochemical Impedance Spectroscopy

Params

• current: Initial current in Ampere.

• amplitude_current: Sinus amplitude in Ampere.

• initial_frequency: Initial frequency in Hertz.

• final_frequency: Final frequency in Hertz.

• frequency_number: Number of frequencies.

• duration: Overall duration in seconds.

• vs_initial: If step is vs. initial or previous. [Default: False]

• time_interval: Maximum time interval between points in seconds. [Default: 1]

• current_interval: Maximum time interval between points in Amps. [Default: 0.001]

• sweep: Defines whether the spacing between frequencies is logarithmic ('log') or linear ('lin'). [Default: 'log']

• repeat: Number of times to repeat the measurement and average the values for each frequency. [Default: 1]

• correction: Drift correction. [Default: False]

• wait: Adds a delay before the measurement at each frequency. The delay is expressed as a fraction of the period. [Default: 0]

CV

Performs a CV scan.

Params

• start: Start voltage. [Default: 0]

• end: End voltage. Boundary voltage in forward scan. [Default: 0.5]

• E2 Boundary voltage in backward scan. [Default: 0]

• Ef End voltage in the final cycle scan [Default: 0]

• step: Voltage step. dEN/1000 [Default: 0.01]

• rate: Scan rate in V/s. [Default: 0.01]

• average: Average over points. [Default: False]

MPP_Tracking

Performs MPP tracking.

Params

• run_time: Run time in seconds.

• init_vmpp: Initial v_mpp.

• probe_step: Voltage step for probe. [Default: 0.01 V]

• probe_points: Number of data points to collect for probe. [Default: 5]

• probe_interval: How often to probe in seconds. [Default: 2]

• record_interval: How often to record a data point in seconds. [Default: 1]

MPP

Runs MPP tracking, finding the initial Vmpp by first measuring Voc, then performing a CV scan from 0 to Voc.

Params

• run_time: Run time in seconds.

• probe_step: Voltage step for probe. [Default: 0.01 V]

• probe_points: Number of data points to collect for probe. [Default: 5]

• probe_interval: How often to probe in seconds. [Default: 2]

• record_interval: How often to record a data point in seconds. [Default: 1]

MPP Cycles

Runs multiple MPP cycles, performing Voc and CV scans at the beginning of each.

Params

• run_time: Run time in seconds

• scan_interval: How often to perform a CV scan.

• probe_step: Voltage step for probe. [Default: 0.01 V]

• probe_points: Number of data points to collect for probe. [Default: 5]

• probe_interval: How often to probe in seconds. [Default: 2]

• record_interval: How often to record a data point in seconds. [Default: 1]

Find Devices

A convenience script for finding connected devices.

Use

From a terminal run python -m easy_biologic.find_devices.

Low Level API

The low level API gives direct control of the Biologic device using the provided DLL libraries. The subpackage contains five modules.

EC Lib

Contains methods converting the BL_* DLL functions for use, enumeration classes to encapsulate program and device states, and C Structures for sending and receiving data from th device.

Methods

• connect( address, timeout = 5 ): Connects to the device at the given address.

• disconnect( idn ): Disconnects given device.

• is_connected( address ): Checks if the device at the given address is connected.

• is_channel_connected( idn, ch ): Checks whether the given device channel is connected.

• get_channels( idn, length = 16 ): Returns a list of booleans of whether the cahnnel at the index exists.

• channel_info( idn, ch ): Returns a ChannelInfo struct of the given device channel.

• get_hardware_configuration( idn, ch ): Returns a HarwareConf struct of the given device channel.

• set_hardware_configuration( idn, ch, mode, connection ): Sets the hardware configuration of the given device channel.

• load_technique( idn, ch, technique, params, first = True, last = True, verbose = False ): Loads the technique with parameter on the given device channel.

• create_parameter( name, value, index, kind = None ): Creates an EccParam struct.

• update_paramters( idn, ch, technique, params, tech_index = 0 ): Updates the paramters of a technique on teh given device channel.

• cast_parameters( parameters, types ): Cast parameters to given types.

• start_channel( idn, ch ): Starts the given device channel.

• start_channels( idn, ch ): Starts the given device channels.

• stop_channel( idn, ch ): Stops the given device channel.

• stop_channels( idn, chs ): Stops the given device channels.

• get_values( idn, ch ): Gets the current values and states of the given device channel.

• raise_exception( err ): Raises an exception based on a calls error code.

• is_in_SP300_family( device_code ): Determines if the given device is in the SP300 device family.

Enum Classes

• DeviceCodes: Device code for identifying model.
  Values: [ KBIO_DEV_VMP, KBIO_DEV_VMP2, KBIO_DEV_MPG, KBIO_DEV_BISTAT, KBIO_DEV_MCS_200, KBIO_DEV_VMP3, KBIO_DEV_VSP, KBIO_DEV_HCP803, KBIO_DEV_EPP400, KBIO_DEV_EPP4000, KBIO_DEV_BISTAT2, KBIO_DEV_FCT150S, KBIO_DEV_VMP300, KBIO_DEV_SP50, KBIO_DEV_SP150, KBIO_DEV_FCT50S, KBIO_DEV_SP300, KBIO_DEV_CLB500, KBIO_DEV_HCP1005, KBIO_DEV_CLB2000, KBIO_DEV_VSP300, KBIO_DEV_SP200, KBIO_DEV_MPG2, KBIO_DEV_ND1, KBIO_DEV_ND2, KBIO_DEV_ND3, KBIO_DEV_ND4, KBIO_DEV_SP240, KBIO_DEV_MPG205, KBIO_DEV_MPG210, KBIO_DEV_MPG220, KBIO_DEV_MPG240, KBIO_DEV_UNKNOWN ]

• DeviceCodeDescriptions: Description of DeviceCodes.
  Values: [ KBIO_DEV_VMP, KBIO_DEV_VMP2, KBIO_DEV_MPG, KBIO_DEV_BISTAT, KBIO_DEV_MCS_200, KBIO_DEV_VMP3, KBIO_DEV_VSP, KBIO_DEV_HCP803, KBIO_DEV_EPP400, KBIO_DEV_EPP4000, KBIO_DEV_BISTAT2, KBIO_DEV_FCT150S, KBIO_DEV_VMP300, KBIO_DEV_SP50, KBIO_DEV_SP150, KBIO_DEV_FCT50S, KBIO_DEV_SP300, KBIO_DEV_CLB500, KBIO_DEV_HCP1005, KBIO_DEV_CLB2000, KBIO_DEV_VSP300, KBIO_DEV_SP200, KBIO_DEV_MPG2, KBIO_DEV_ND1, KBIO_DEV_ND2, KBIO_DEV_ND3, KBIO_DEV_ND4, KBIO_DEV_SP240, KBIO_DEV_MPG205, KBIO_DEV_MPG210, KBIO_DEV_MPG220, KBIO_DEV_MPG240, KBIO_DEV_UNKNOWN ]

• IRange: Current ranges.
  Values: [ p100, n1, n10, n100, u1, u10, u100, m1, m10, m100, a1, KEEP, BOOSTER, AUTO ]

• ERange: Voltage ranges.
  Values: [ v2_5, v5, v10, AUTO ]

• ElectrodeConnection: Whether the electrode is in standard or grounded mode.
  Values: [ STANDARD, GROUNDED ]

• ChannelMode: Whether the device is floating or grounded.
  Values: [ GROUNDED, FLOATING ]

• TechniqueId: ID of the technique. (Not fully implemented.)
  Values: [ NONE, OCV, CA, CP, CV, PEIS, CALIMIT ]

• ChannelState: State of the channel.
  Values: [ STOP, RUN, PAUSE ]

• ParameterType: Type of a parameter.
  Values: [ INT32, BOOLEAN, SINGLE, FLOAT ] (FLOAT is an alias of SINGLE.)

Structures

• DeviceInfo: Information representing the device. Used by connect().
  Fields: [ DeviceCode, RAMSize, CPU, NumberOfChannles, NumberOfSlots, FirmwareVersion, FirmwareDate_yyyy, FirmwareDate_mm, FirmwareDate_dd, HTdisplayOn, NbOfConnectedPC ]

• ChannelInfo: Information representing a device channel. Used by channel_info().
  Fields: [ Channel, BoardVersion, BoardSerialNumber, FirmwareVersion, XilinxVersion, AmpCode, NbAmps, Lcboard, Zboard, RESERVED, MemSize, State, MaxIRange, MinIRange, MaxBandwidth, NbOfTechniques ]

• HardwareConf: Hardware configuration information for a channel.
  Fields: [ Conn, Ground ]

• EccParam: A technique parameter.
  Fields: [ ParamStr, ParamType, ParamVal, ParamIndex ]

• EccParams: A bundle of technique parameters.
  Fields: [ len, pParams ]

• CurrentValues: Values measured from and states of the device.
  Fields: [ State, MemFilled, TimeBase, Ewe, EweRangeMin, EweRangeMax, Ece, EceRangeMin, EceRangeMax, Eoverflow, I, IRange, Ioverflow, ElapsedTime, Freq, Rcomp, Saturation, OptErr, OptPos ]

• DataInfo: Metadata of measured data.
  Fields: [ IRQskipped, NbRows, NbCols, TechniqueIndex, TechniqueID, processIndex, loop, StartTime, MuxPad ]

Constants

• VMP3_DEVICE_FAMILY: Set of DeviceCodes in the VMP3 device family.
  { DeviceCodes.KBIO_DEV_VMP2, DeviceCodes.KBIO_DEV_VMP3, DeviceCodes.KBIO_DEV_BISTAT, DeviceCodes.KBIO_DEV_BISTAT2, DeviceCodes.KBIO_DEV_MCS_200, DeviceCodes.KBIO_DEV_VSP, DeviceCodes.KBIO_DEV_SP50, DeviceCodes.KBIO_DEV_SP150, DeviceCodes.KBIO_DEV_FCT50S, DeviceCodes.KBIO_DEV_FCT150S, DeviceCodes.KBIO_DEV_CLB500, DeviceCodes.KBIO_DEV_CLB2000, DeviceCodes.KBIO_DEV_HCP803, DeviceCodes.KBIO_DEV_HCP1005, DeviceCodes.KBIO_DEV_MPG2, DeviceCodes.KBIO_DEV_MPG205, DeviceCodes.KBIO_DEV_MPG210, DeviceCodes.KBIO_DEV_MPG220, DeviceCodes.KBIO_DEV_MPG240 }

• SP300_DEVICE_FAMILY: Set of DeviceCodes in the SP300 device family.
  { DeviceCodes.KBIO_DEV_SP200, DeviceCodes.KBIO_DEV_SP300, DeviceCodes.KBIO_DEV_VSP300, DeviceCodes.KBIO_DEV_VMP300, DeviceCodes.KBIO_DEV_SP240 }

Data Parser

Parses data received from a technique and contains technique fields for different device types.

Methods

• parse( data, info, fields = None, device = None ): Parses data received from a technique.

• calculate_time( t_high, t_low, data_info, current_value ): Calculates elapsed time from time data.

Classes

• VMP3_Fields: Contains technqiue fields for VMP3 devices. (Not all techniques are implemented) Properties: [ OCV, CP, CA, CPLIMIT, CALIMIT, CV, PEIS ]

• SP300_Fields: Contains technqiue fields for SP-300 devices. (Not all techniques are implemented) Properties: [ OCV, CP, CA, CPLIMIT, CALIMIT, CV, PEIS ]

EC Find

Implements the BL Find DLL.

Methods

All BL Find DLL functions are implemented under the same name.

• find_devices( connection = None ): Finds conencted devices.

Technique Fields

Parameter types for techniques. (Not all techniques are implemented.)

Classes

• OCV
• CV
• CA
• CALIMIT

EC Errors

Implements EC errors.

Classes

• EcError( value = None, code = None, message = None )

Example

A basic example running an MPP program on channels 0 - 7 for 10 minutes.

import easy_biologic as ebl
import easy_biologic.base_programs as blp


# create device
bl = ebl.BiologicDevice( '192.168.1.2' )

# create mpp program
params = {
	'run_time': 10* 60		
}

mpp = blp.MPP(
    bl,
    params, 	
    channels = [ 0, 1, 2, 3, 4, 5, 6 ]        
)

# run program
mpp.run( 'data' )

Following is an example running a CV scan for three cycles at a scan rate of 50 mV/s in channel 0. The experiment begins at 0.5 V and forward scans to -0.25 V, then scans backward to 0.8 V. In the final cycles, it scans to 1.0 V and finish the experiment.

import easy_biologic as ebl
import easy_biologic.base_programs as blp        

bl = ebl.BiologicDevice( '192.168.1.2' )

save_path = '/save_path/CV.csv'
    
params = {
    'start': 0.5,
    'end': -0.25,
    'E2': 0.8,
    'Ef': 1.0,
    'rate': 0.05,  
    'step': 0.001,    
    'N_Cycles': 2,
    'begin_measuring_I': 0.5,
    'End_measuring_I': 1.0,
}  

CV = blp.CV(
    bl,
    params,     
    channels = [0]   #channel is to be claimed.
)     

#run program and save data into csv file.
CV.run( 'data' )
CV.save_data(save_path)

Following is an example that run the OCV and use the OCV as the voltage in PEIS test.

import easy_biologic as ebl
import easy_biologic.base_programs as blp        

bl = ebl.BiologicDevice( '192.168.1.2' )

save_path_ocv = '/save_path/OCV.csv'

# Run OCP test
params_ocv = {
    'time': 2,
    'time_interval': 1,
}

ocv = blp.OCV(
    bl,
    params_ocv,
    channels=[0]
    )

ocv.run('data')
ocv.save_data(save_path_ocv)

voc = {
    ch: [datum.voltage for datum in data]
    for ch, data in ocv.data.items()
}

voc = {
    ch: sum(ch_voc) / len(ch_voc)
    for ch, ch_voc in voc.items()
}

# Run PEIS test
save_path_peis = '/save_path/PEIS.csv'

params_peis = {
    'voltage': list(voc.values())[0],
    'final_frequency': 1000,  # frequency unit: Hertz
    'initial_frequency': 1000000,  # frequency unit: Hertz
    'amplitude_voltage': 0.1,  # voltage unit: Volt
    'frequency_number': 60,
    'duration': 0,  # time unit: second
    'repeat': 10,
    'wait': 0.1
}

peis = blp.PEIS(
    bl,
    params_peis,
    channels=[0]
)

peis.run('data')
peis.save_data(save_path_peis)