KSFoundation  [April-2021]
A platform for simpler EPIC programming on GE MR systems
EPIC using KS Foundation

KS Foundation is a C-library with additional support functions and sequence modules for simpler pulse sequence programming on GE MR-systems using EPIC. This has been developed by the Neuro MR Physics group at Karolinska University Hospital, Stockholm, Sweden. The KS Foundation library acts as an abstraction layer, aiming at keeping information encapsulated and low-level EPIC functions hidden to the programmer. While the programming language is still C, without the ability to create actual C++ classes, typedef structs are used as class surrogates with a systematically named set of functions associated to them. While not strictly true, an instance of one of these typedef structs is referred to as a sequence object.

– The Neuro MR Physics group, Karolinska University Hospital

KSFSequenceObjects.png
KS Foundation Sequence Objects

Key features

  • Self-contained sequence parts
  • No use of integer amplitudes or CVs for pulses/pulseparts (pw_***, a_***, ia_***)
  • Custom gradient waveforms in [G/cm] and THETA waveforms in [degrees]
  • No EPIC Macros (except for KS_SEQLENGTH())
  • RF selection by one-line assignment
  • Automatic memory allocation for waveforms and trapezoids
  • Automatic RF and gradient counting for SAR and heating calculations
  • Arbitrary placement of one designed sequence object multiple times on different sequence boards
  • Sequence objects (KS_***) are built on other sequence objects to inherit functionality and increase consistency
  • Ability to build on existing sequence objects to make new sequence specific objects, or a whole sequence
  • ScanOnHost: Scan clock, TR timing, SAR-limits and PNG/SVG/PDF generation performed on HOST by calling scan loop functions on TGT
  • GERequired.e keeps mandatory stuff out of sight
  • Interactive HTML/Javascript plotting of the sequence on HOST



Documentation Overview

If you are new to EPIC, please have a first look at EPIC Crash Course, and then navigate around in ksgre_tutorial.e

The documentation is now grouped into categories in the [Modules tab]

Further details on some KS Foundation related features and functionality:

  1. KS_PHASEENCODING_PLAN
  2. Plotting (interactive HTML format on HOST)
  3. KS Foundation sequence objects (Data Structures)
  4. KS Foundation functions, some of which are
    • ks_eval_***() (to design sequence objects in cveval())
    • ks_pg_***() (to place sequence objects in the @pg section)
    • ks_scan_***() (to modify sequence objects in scan())
  5. GERequired functions
  6. Selection of GE RF pulses as KS_RF objects (see also KSFoundation/rfpulses/*.eps)
  7. KS Foundation defines
  8. KS Foundation enumerations



Installation

Supported releases

As of May 2020, the support for releases 24 and 25 have been dropped. The KS Foundation sequences now supports the following releases without need to change the code:

  • DV26.0_R01
  • DV26.0_R02 (also compiles R03-R05)
  • MP26.0_R01
  • MP26.0_R02
  • PX26.1_R01
  • DV27.1_R01
  • RX27.0_R02
  • RX27.0_R03
  • MR28.0_R03
  • MR28.0_R04
  • DV28.0_R01
  • VX28.0_R01
  • VX28.0_R02
  • VX28.0_R03
  • MR29.0_R01
  • MR29.1_R01


Basic installation

  1. Clone the Git repository https://gitlab.com/neuromr_karolinska/psd_ksfoundation to a linux machine with EPIC installed (releases from 26 and later).
    • Account on GitLab.com is required, please fill in the following form: http://goo.gl/forms/UKxgOYGFhPZgxDwr2 to get access to this repository (If this method fails, please send your GitLab username to: mrphy.nosp@m.sics.nosp@m.@neur.nosp@m.orad.nosp@m.karol.nosp@m.insk.nosp@m.a.se).
      > cd /somepath/toput/mypsds/
      > git clone https://gitlab.com/neuromr_karolinska/psd_ksfoundation // use your GitLab.com user/passwd
    • The psd_ksfoundation repository contains the following directories:
      Documentation/ // This documentation
      KSFoundation/ // The KS Foundation library, GERequired.e and other support files
      ksfse/ // The Fast Spin Echo sequence. ksfse.e (2D/3D)
      ksgre/ // The Gradient Echo sequence. ksgre.e (2D/3D)
      ksgre_tutorial/ // A simplified version of ksgre.e
      ksepi/ // The Echo Planar sequence. ksepi.e (2D/3D)
      ksmodules/ // General sequence plugins (a.k.a. sequence modules) for various sequences
  2. Make sure KSFoundation/common.mk has a matching entry for your ESE top path
    • Check the name of your ESE top-level directory (e.g. /ESE_RX27.0_R02). Many recent ESE distributions are already in common.mk, so you may not need to do anything. Including this file in the Imakefile of each psd is already taken care of, and will set the RELEASE_NUM (and PATCH_NUM) variable in the Imakefile, so the psds can compile for multiple ESE releases without need for changing the psd source code.
  3. If not already done, run setupESE to set your ESE variables (see GE's EPIC installation manual). Releases from DV24 and later are supported with KS Foundation EPIC.
  4. Try to compile e.g. ksgre.e in ksgre/ by
    > prep_psd_dir
    > psdqmake clean all


Install DDD to debug in WTools (HOST & TGT), or use VSCODE

Please take the time to install the DDD debugger or equivalent, it's a time investment. The debugger choice is located in GE's .psdtoolsrc (Debugger = "ddd") in your home directory and can be used both in EvalTool and MGDSim. There is nothing special about KS Foundation here other than it is very easy to see the sequence structs and its contents this way, all in one place.