Package Configuration

Package Configuration

Most of the EMsoft programs require a number of predefined parameters that are used to define the locations of the EMsoft resources, the name list template files, and so on. While there are several ways to implement this, we have opted to create a configuration file for EMsoft. Before you execute any of the EMsoft programs, you must properly set up the configuration file, which is done with the EMsoftinit program, which you must execute from inside the Bin folder:

	cd BuildFolder/Bin
    ./EMsoftinit

This program will ask for a number of parameters:

 EMsoft version 4_0_0, Copyright (C) 2001-2018 Marc De Graef Research Group/CMU
 EMsoft comes with ABSOLUTELY NO WARRANTY.
 This is free software, and you are welcome to redistribute it
 under certain conditions; see License.txt file for details.


 Program name : EMsoftinit
 Purpose      : Initialize the EMsoft configuration file
 Platform     : Darwin

 Jun  1 2018   9:08:29.064 AM


 ------
 Please respond to the following questions (each entry < 132 characters)
  Enter your user name : 

Enter your full name

  Enter your email address : 

Some of the EMsoft programs have the ability to send you email when the run has completed, so you should enter a valid email address here.

  Enter your affiliation : 

Typically this would be your university or national lab name, or company name. The program then prints the following information:

 A skeleton EMsoftConfig.json file has been created in your .config/EMsoft folder.
 You will need to edit this file to change the parameters from their default values.
 
 - EMsoftpathname should point to the top folder of your EMsoft installation.
 - EMdatapathname should point to where you want to keep all EMsoft output files.
   Note that this folder should NOT be inside the EMsoftpathname folder!
   You may leave this variable undefined (empty string) to force programs to
   generate all files in the current working folder or to use full path file names.
 - EMXtalFolderpathname should point to the folder that will contain the *.xtal files.
 - EMtmppathname should point to the tmp folder where the EMsoftConfig.json file is located.
 - EMsoftLibraryLocation is needed only if you have a fully functional IDL installation; this
   variable should then point to the location of the EMsoftLib.dylib or EMsoftLib.dll file.
 - One of the variables Develop and Release should be set to Yes, the other to No; if you are
   developing new EMsoft code using the EMsoftPrivate folder, then set Develop to Yes
   and Release to No to indicate Debug mode. for regular users: Develop=No, Release=Yes
 - EMNotify can be set to Slack or Email to send program completion messages to the user
 - EMSlackWebHookURL and EMSlackChannel are used for Slack messages (see Package Configuration wiki)
 
 Make sure that each non-empty pathname ends with /, even on Windows platforms ! 
 
 Every EMsoft program will read this configuration file to figure out where things are located.

The program has created a .config/EMsoft folder in your top user folder; inside this folder, a file named EMsoftConfig.json has been created, and this file needs to be edited to complete the configuration process.

• EMsoftpathname: this is the full path location of your EMsoft distribution folder and should end with the / character (the json standard only allows the / character for folder separation, even on Windows systems).
• EMdatapathname: this is the full path name to the folder that you will use to store all your data files. EMsoft programs will pre-pend this string to all filenames defined in name list input files. If you do not want this, that you can leave this string blank, and then all generated files will be located inside the folder from which you executed the program (i.e., the default UNIX behavior).
• EMXtalFolderpathname: all EMsoft programs require a crystal structure to properly function. Those files, which typically have extension .xtal, are all kept inside the XtalFolder folder and you must specify its location. It is recommended that you keep this folder inside the EMdatapathname folder.
• EMtmppathname: for some programs, EMsoft needs to store temporary data, and this variable points to the corresponding folder. You can either use the system's /tmp folder or use the .config/EMsoft/tmp folder, which is automatically created by EMsoftinit.
• EMsoftLibraryLocation: if you have a complete IDL installation on your system, then this parameter should point to the location of the Build/Bin folder.
• EMNotify: some programs take a long time, and they have an option to notify the user via an email message or a Slack push when they are done. Setting this variable to "Off" will turn off the notification system; setting it to Email will send a message to the e-mail address defined in the configuration file. Setting the parameter to Slack will push a Slack message and requires definition of two additional parameters, EMSlackWebHookURL and EMSlackChannel, as described in a separate section below.

Once you have properly defined all configuration parameters, save the EMsoftConfig.json file and now you are ready to start using the package.

Slack Messaging

Slack notifications require that the user set up a slack.com message channel. To do so, first obtain a team Slack URL of the form your-team-url.slack.com; even if you are just working by yourself, you will still need to set up a team. You could, for instance, name your team in the following form: institution-EMsoft.slack.com, where institution is the abbreviation for your university or research entity. Then you provide your email address and a password to complete the set up of your slack account (this is the free account).

Once you have a team URL, you will find that you have two default message channels, #general and #random; we suggest that you create an #EMsoft channel as well. At this point, you may want to also install the desktop and/or mobile slack app which you can download from the slack.com site or via the Apple Store for Mac OS X users. You can access your slack.com account via a web browser or via the app. You will also need to allow slack to push notifications to your desktop/mobile.

Next, you will need to set up incoming webhook integration. Point your browser to [https://api.slack.com/custom-integrations]; select the Incoming Webhooks menu item. In the first section titled Send data into Slack in real-time, click on the incoming webhook integration link in the paragraph starting with Start by setting up .... You will get a page titled Incoming Webhooks; select the name of the channel that you wish to use for messaging from the pull down menu in the Post to Channel form. Then click the green button, which will get you to an integration settings page. From this page you will need to copy the Webhook URL entry into you EMsoftConfig.json configuration file; this is a long entry with several code strings in it that uniquely define your message channel, so you should not share this URL with anyone else (unless you want that person to be able to post messages to your channel).

In the EMsoftConfig.json file, edit the following three lines:

``EMNotify'': ``Slack'',
``EMSlackWebHookURL'': ``https://hooks.slack.com/services/T6.../B6...'',
``EMSlackChannel'': ``channelname'',

where channelname must be replaced by the name of the channel you want messages to be posted to (without the # character). On the Integration Settings page, check the other items and customize as needed, then Save the Settings. You should now have a functioning EMsoft Slack message channel! Try it by running the EMsoftSlackTest program from the command line...