KSFoundation  [October2024]
A platform for structured EPIC programming on GE MR systems
HowTo - Get Started

Home



Supported releases

The KS Foundation sequences now supports the following releases without need to change the code:

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


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_to_put_my_psds/
      > 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 e.g. plotting tools
      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. /MR30.1_R01). 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. Compile KSFoundation in the KSFoundation/<YOURVERSIONNUMBER> folder
    > psdqmake clean all
  5. Compile a sequence, e.g. ksgre.e in the ksgre/ folder, by
    > prep_psd_dir
    > psdqmake clean all



Build your first KSFoundation sequence

Each sequence that is shipped with KSFoundation "lives" in its own folder named ks***/. You can copy one of those folders to use as a starting point for your sequence (e.g. ksgre_tutorial is a simple one to start from). Here, is a step by step guide to generating your own sequence:

  1. Name your sequence and copy over the KSFoundation sequence you want to use as template to a new directory with your sequence name.
    > cp -r ksgre_tutorial/ mysequence
  2. In your new directory, remove all files except the ***.e files and the Imakefiles (you should have three files and one symbolic link remaining after this).
    > cd mysequence/
    > rm -r !(*.e|Imakefile*)
    > rm .* // delete hidden files
  3. Rename the remaining ***.e files to your sequence name.
    > mv ksgre_tutorial.e mysequence.e
    > mv ksgre_tutorial_implementation.e mysequence_implementation.e
  4. Now, it is time to start editing the contents of the files. First, let's change all references to the original filename. This is easiest to do using a find and replace tool in your code editor (e.g. find all ksgre_tutorial and replace with mysequence).
    • In the Imakefile you need to change the PSD name to your sequence name.
    • In the main ***.e file you need to make sure you include the implementation file to your sequence.
    • In the ***_implementation.e file you need to change the psdname to your sequence name.
  5. At this point you should be able to compile the sequence. In the sequnce folder run:
    > prep_psd_dir
    > psdqmake clean all
  6. Now, you can edit mysequence to do whatever you would like it to do. Most commonly you will only need to work in the ***_implementation.e file that contain functions that get called by the functions in the ***.e file. For more details on KSFoundation objects, looping structure, modules, functions etc. Check out the other HowTos and specific Documentation on this page.
  7. When you are ready to test your sequence on a scanner you need to successfully compile it again (step 5) for the correct release version for your scanner. Then you need to move the generated binaries to the scanner as described in the next section.



Run your KSFoundation sequence

Once you have built your sequence and successfully compiled it locally, you can try running it on your scanner following these steps:

  1. Copy the psd binaries to the scanner, e.g. to the folder /usr/g/research/. Depending on your release version the folder where the binaries are stored after compilation with psdqmake clean all can be called slightly different things. The binary for the HOST is in a folder called host or host32 and is named by your sequence name (e.g. mysequence) without any extension. The binary for the TGT is in a folder called tgt, tgt_ice, agp, ice_agp, tgt_mgd or tgt_ice, and will have an extension of either .mgd or .ice (e.g. mysequence.psd.ice). For example, to copy files on MR30.1_R01 you would need to run the following commands (assuming the scanner is available on your network):
    > ssh sdc@scannername mkdir -p /usr/g/bin/mysequence/ // create new folder if it doesnt't exist
    > ssh sdc@scannername rm -f /usr/g/bin/mysequence/mysequence // remove old binary if it exists
    > ssh sdc@scannername rm -f /usr/g/bin/mysequence/mysequence.psd.ice // remove old binary if it exists
    > scp host32/mysequence sdc@scannername:/usr/g/bin/mysequence/mysequence // copy host binary
    > scp ice-agp/mysequence.psd.ice sdc@scannername:/usr/g/bin/mysequence/mysequence.psd.ice // copy tgt binary
  2. Set up symbolic links from /usr/g/bin/mysequence (where the scanner looks for sequence binaries) to the binaries in /usr/g/research/mysequence. To run from your local computer:
    > ssh sdc@scannername ln -fs /usr/g/research/mysequence/mysequence /usr/g/bin/mysequence
    > ssh sdc@scannername ln -fs /usr/g/research/mysequence/mysequence.psd.ice /usr/g/bin/mysequence.psd.ice
  3. Make sure sdc has permissions to execute the binaries.
    > ssh root@scannername chmod 755 /usr/g/research/mysequence/mysequence
    > ssh root@scannername chmod 755 /usr/g/research/mysequence/mysequence.psd.ice
  4. Now you should be able to run your sequence by specifying mysequence in Imaging Options...->More->PSD Name on your scanner!




Home