Rt/issue75 shim specs json

+b0shim/+coils/+greg/Contents.m

@@ -0,0 +1,8 @@
+%b0shim.coil.greg 8-channel AC/DC 3T neck coil
+% 
+% Nicknamed "greg", after its creator: 
+% [Germain G. et al., ISMRM 2016](https://cds.ismrm.org/protected/16MPresentations/abstracts/1154.html)
+%
+% [Topfer et al., ISMRM 2018](https://www.slideshare.net/neuropoly/integrated-rf-and-shim-coils-for-mri-105560384)
+%
+% <iframe src="//www.slideshare.net/slideshow/embed_code/key/lhvoyKuHLsgc8L" width="595" height="485" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen> </iframe> <div style="margin-bottom:5px"> <strong> <a href="//www.slideshare.net/neuropoly/integrated-rf-and-shim-coils-for-mri-105560384" title=" Integrated RF and Shim coils for MRI" target="_blank"> Integrated RF and Shim coils for MRI</a> </strong> from <strong><a href="https://www.slideshare.net/neuropoly" target="_blank">NeuroPoly </a></strong> </div>

+b0shim/+coils/+greg/specs.json

@@ -0,0 +1,81 @@
+{
+    "Adc": {
+        "mVPerAdcCount": 2
+    },
+    "Id": {
+        "systemName": "Greg",
+        "channelNames": [
+            "Ch1",
+            "Ch2",
+            "Ch3",
+            "Ch4",
+            "Ch5",
+            "Ch6",
+            "Ch7",
+            "Ch8"
+        ],
+        "channelUnits": [
+            "[A]",
+            "[A]",
+            "[A]",
+            "[A]",
+            "[A]",
+            "[A]",
+            "[A]",
+            "[A]"
+        ]
+    },
+    "Amp": {
+        "maxCurrentPerChannel": [
+            2.5,
+            2.5,
+            2.5,
+            2.5,
+            2.5,
+            2.5,
+            2.5,
+            2.5
+        ],
+        "maxCurrentPerBank": 20,
+        "nChannels": 8,
+        "nActiveChannels": 8,
+        "maxVoltagePerChannel": 2500,
+        "staticChannels": [
+            true,
+            true,
+            true,
+            true,
+            true,
+            true,
+            true,
+            true
+        ],
+        "dynamicChannels": [
+            true,
+            true,
+            true,
+            true,
+            true,
+            true,
+            true,
+            true
+        ]
+    },
+    "Com": {
+        "baudRate": 115200,
+        "readTimeout": 500,
+        "dataBits": 8,
+        "stopBits": 1,
+        "flowControl": "NONE",
+        "parity": "NONE",
+        "byteOrder": "bigEndian",
+        "txRxDelay": 0.005,
+        "updatePeriod": 0.1
+    },
+    "Dac": {
+        "resolution": 8,
+        "maxCurrent": 5,
+        "referenceVoltage": 1250,
+        "maximum": 26214
+    }
+}

+b0shim/+coils/+greg/write_config.m

@@ -0,0 +1,75 @@
+function [ filename ] = write_config( filename )
+%WRITE_CONFIG Writes system configuration file for the 8 ch. AC/DC neck coil
+%     
+%     filename = b0shim.coils.greg.write_config();
+%     b0shim.coils.greg.write_config( filename );
+%
+% Defines the system configuration and saves it to the coil's package folder under
+% ```
+%   ./+b0shim/+coils/+greg/config.json
+% ```
+% b0
+%
+% and saves the system configuration for
+% the 3T 8-channel AC/DC neck-coil 
+% 
+% See also
+% [ b0shim.coils.greg.Contents ]( ./Contents.md )
+    arguments
+        filename(1,:) char = [mfilename('fullpath') filesep 'config_' datestr(date,'yymmdd') ];
+    end
+warning('Untested commit - may contain bugs')
+
+%% 1. Create an instance of the default configuration object
+config = b0shim.Config;
+
+%% 2. *As the object's properties are immutable*, convert to struct:  
+% NOTE: Conversion elicits a warning. Not a concern. Mute it momentarily)
+warning('OFF', msgId);
+config = struct( config );
+warning('ON', msgId);
+
+%% 3. Assign fields according to system specs 
+
+% System/package name
+config.name = "greg"; 
+
+%% Channel configuration
+
+% Add 8 channels
+config.channels(1:8) = b0shim.parts.Channel ; 
+
+% Assign channel properties 
+for iCh = 1 : numel(config.channels)
+    config.channels(iCh).name  = strcat( "Ch. ", num2str(iCh) );
+    config.channels(iCh).units = "A"; % Amperes
+    config.limits(iCh)         = [-2.5 2.5]; % [min. max.] in Amperes 
+    config.positioning         = "table-fixed";  % shim position is table-dependent
+end
+
+%% Configuration of serial port parameters
+config.ports(1) = b0shim.parts.Port();
+
+% NOTE: These parameters are actually set *in the source code of the Teensy
+% microcontroller.*
+% TODO: Rather than hardcode the values in two places, some consistency ought
+% to be enforced between the C++ and MATLAB sources, e.g. by MATLAB parsing the
+% .cpp/.hpp files, or the config.json values being transfered over serial, or
+% some other alternative. (Same goes for the Arduino-based respiratory bellows...) 
+
+config.ports(1).BaudRate    = 115200;
+config.ports(1).DataBits    = 8;
+config.ports(1).StopBits    = 1;
+config.ports(1).Parity      = "none"
+config.ports(1).FlowControl = "none";
+config.ports(1).ByteOrder   = "big-endian";
+
+%% Configure remaining properties related to the microcontroller
+
+%% 4. With everything configured, convert back to object
+config = b0shim.Config( config );
+
+%% 5. Save as .json
+write_json( config, filename )
+
+end

+b0shim/+parts/Channel.m

@@ -0,0 +1,82 @@
+classdef Channel 
+%b0shim.parts.Channel Defines a shim coil element
+%        
+%    self = b0shim.parts.Channel()
+%
+% `Channel` provides a template description of a single coil element. The
+% properties of a `Channel` object-array thereby describe an array of coils.
+%
+% See also  
+% [ b0shim.parts.Contents ](./Contents.md)  
+% [ b0shim.Config ](../Config.md)  
+
+properties
+
+    % Shim channel ID as a string-scalar.
+    %
+    % `name` defines the row names when tabulating optimization results 
+    % in `b0shim.Opt.optimizeshimcurrents` (i.e. for print display).
+    %
+    % __EXAMPLE__ 
+    % 
+    % % Generically, this could simply be  
+    % `name = "Ch. 1"`; 
+    %
+    % % Or, for a 2nd-order spherical harmonic term  
+    % `name = "XY (B22)"`; 
+    name(1,1) string  = "Ch" ;
+
+    % Shim channel physical units as a string-scalar.
+    %
+    % `units` is used when tabulating optimization results in
+    % `b0shim.Opt.optimizeshimcurrents` (i.e. for print display).
+    %
+    % __EXAMPLE__ 
+    % 
+    % % Units are often expressed in Amperes  
+    % `units = "A"`;
+    %
+    % % Alternatively, for a 2nd-order spherical harmonic shim, units could be
+    % `units = "mT/m^2"`;
+    units(1,1) string = "A" ;
+
+    % Range of permitted values as 2-element vector.
+    % 
+    % `limits` defines the default constraints during shim optimization:
+    % `limits(1)` specifies the minimum value; 
+    % `limits(2)` specifies the maximum value.
+    % 
+    % Both elements should be given in the corresponding `units`.
+    %
+    % __EXAMPLE__
+    % 
+    % For an "AC/DC" multi-coil array, with `units="A"`, the value might be 
+    % `limits = [-2.5 2.5];`. 
+    limits(1,2) {mustBeNumeric,mustBeReal} ; 
+
+    % Label specifying coil positioning mode as a string-scalar.
+    % 
+    % Options for `positioning` are:  
+    %
+    % - "iso-fixed": The coil is immobile relative to isocenter (e.g. a gradient coil)
+    %
+    % - "table-fixed": The coil position changes with the patient-table (e.g. spine shim array)
+    % 
+    % - "": Otherwise (e.g. coils can be freely rearranged)
+    positioning(1,1) string {mustBeMember(positioning,["iso-fixed" "table-fixed" ""])} = "iso-fixed";
+end
+
+% =========================================================================
+% =========================================================================
+methods 
+% =========================================================================
+function self = Channel( props )
+    return
+end
+% =========================================================================
+
+end
+% =========================================================================
+% =========================================================================
+
+end

+b0shim/+parts/Contents.m

@@ -0,0 +1,12 @@
+% b0shim.parts — Shim system components
+% 
+% Classes in `+b0shim/+parts` define parameter templates for specific shim
+% system components. Practically, the classes define properties of the general
+% system configurations (namely, config.json files on disk and `b0shim.Config`
+% objects in memory). The classes consist only of properties and their
+% constructors likely won't need to be called except when creating a new
+% configuration.  
+% 
+% Files
+%   Channel - A shim coil element
+%   Port    - Serial port protocol parameters

+b0shim/+parts/Port.m

@@ -0,0 +1,67 @@
+classdef Port 
+%b0shim.parts.Port Serial port protocol parameters
+%    
+%    self = b0shim.parts.Port()
+% 
+% `Port` properties are simply 6 of the 7 the parameters passed to MATLAB's
+% `serialport` function when opening the communication line between a PC and
+% the microcontroller directing the shim amplifiers. Hence, the properties are
+% only relevant for hardware systems permitting direct control via MATLAB—USB
+% (i.e. systems that subclass `b0shim.Com` to define a communication interface).
+% For a host MRI, or a virtual shim array, this classdef is likely irrelevant.
+%
+% __NOTES__  
+%
+% 1. While `Port` properties all correspond to `serialport()` arguments,
+% some of the default assignments are different (`Port` defaults are informed
+% by the microcontrollers in use at our lab).
+%
+% 2. As a safety feature, the mandatory first argument to `serialport()`—the
+% device ID—is not included as a `Port` property: when connecting to a device,
+% a user still needs to specify the port name. (The parameter, in any case,
+% tends to vary as device names are determined by the OS.)
+% 
+% See also  
+% [ serialport ](https://www.mathworks.com/help/matlab/ref/serialport.html)  
+% [ b0shim.parts.Contents ](./Contents.md)  
+% [ b0shim.Config ](../Config.md)  
+
+properties
+
+    % 2nd argument to serialport
+    BaudRate(1,1) uint32 {mustBeInteger,mustBePositive} = 9600;
+
+    % Name-value argument to serialport
+    DataBits(1,1) uint8 {mustBeMember(DataBits, [8 7 6 5] )} = 8;
+
+    % Name-value argument to serialport
+    Parity(1,1) string {mustBeMember(Parity, ["none" "even" "odd"])} = "none";
+
+    % Name-value argument to serialport
+    StopBits(1,1) single {mustBeMember(StopBits, [1 1.5 2] )} = 1;
+
+    % Name-value argument to serialport
+    FlowControl(1,1) string {mustBeMember(FlowControl, ["none" "hardware" "software"] )} = "none";
+
+    % Name-value argument to serialport
+    ByteOrder(1,1) string {mustBeMember(ByteOrder, ["little-endian" "big-endian"] )} = "big-endian";
+
+    % Name-value argument to serialport
+    Timeout(1,1) single {mustBeNumeric, mustBePositive} = 10;
+
+end
+
+% =========================================================================
+% =========================================================================
+methods 
+% =========================================================================
+function self = Port( )
+    return
+end
+% =========================================================================
+
+end
+% =========================================================================
+% =========================================================================
+
+end