Dear BETA-tester, You just received a BETA-test version of the Virtual NMR Spectrometer (VNMR). It is already operational and almost complete, as you will find out yourself. However, it still has a long way to go till it becomes a complete, bug-free program package. You will certainly find some bugs that we overlooked (see the list of known issues below). You may also notice that some parts of the program are still under construction. I hope that with your help we will be able to bring this program up to the level of full completeness. Therefore, your input on all aspects of the Virtual Spectrometer is so valuable to us. I look forward to hearing about your experience in using the Virtual Spectrometer. Please email me all your questions/suggestions/comments/etc, in particular, but not limited to: -- pulse sequences that you simulated; -- bug/problem reports; -- suggestions on bug fixes; -- suggestions on improvements of the source code; -- suggestions regarding general appearance of the interfaces and their improvements. All questions and answers of general interest will then be forwarded to all of you. Please feel free to propose your own modifications/enhancements of the source code. Your suggestions are extremely valuable for the development of the program, and I will try to incorporate them in the package as appropriate (with a proper acknowledgement, of course). INSTALLATION: Follow all instructions in the attached Install.html file. It is highly recommended that you go through the User's Manual (located in VS/manuals/vs_Manual.html) prior to configuring and using the Virtual NMR Spectrometer. If you are using Win95, 2000, or XP, there is a good chance that the excecutable version of the xlator included in the package will work on your machine, so you might not need to compile the xlator. I suggest that you first try running the program and if it can translate a simple pulse program like zg or cosysh, you can skip the compilation step. There are also few illustrative examples in the Tutorial section: I am currently in a process of making similar tutorials for all experiments we tested so far. More examples are presented in our JMR paper and on our Web site: http://www.vsnmr.org. The Virtual NMR Spectrometer package became possible thanks to significant contribution from Konstantin Berlin, Vlad Ruchinsky, Peter Nicholas, and David Cowburn. Thanks to numerous ALPHA-testers (particularly Sami Heikkinen, Emeric Miclet, Olivier Walker, and Paul Vasos) for their valuable feedback that helped develop and improve the current version of the program. Special thanks to Ulrich Guenther for advice regarding data conversion from XWINNMR and to Frank Delaglio for help with data conversion to NMRPipe. This project is supported by grants from the National Science Foundation and from the Camille and Henry Dreyfus Foundation. Thanks again for your willingness to participate in the BETA-testing of the Virtual NMR Spectrometer. I hope you will enjoy it. David Fushman Jan.31, 2004 ____________________________________________________________________________ last update: Feb 02, 2004 USEFUL INFORMATION and KNOWN ISSUES (adopting Microsoft language...) 1. TRANSLATOR. The current version of the translator, written by Vlad Ruchinsky, understands and treats properly most statements in Bruker programming language. However, it does not yet treat properly the following statements (these issues will be fixed, eventually): UNBLKGRAD/BLKGRAD and setnmr commands which have nothing to do with spin-system evolution, are not recognized and must be commented out, e.g. '4u BLKGRAD' --> '4u ;BLKGRAD' variable lists (variable delay, pulse, counter, etc lists) are currently not recognized recent MC/FnMode syntax from Bruker is not recognized: the pulse programs have to be written with explicit implementation of a particular scheme for frequency discrimination (e.g. States, TPPI, etc). #include -- if #include statement is present in the pulse program, xlator looks for the specified include file in the current (vs_pp) directory. If it finds it there, the include file will be appended and analyzed together with the main pulse program; if not -- an error message will be displayed. Some technical settings usually present in the standard include files (e.g. #define H2_LOCK setnmr8^4) are currently not recognized by the translator. You have to comment them out (use ';'). Commenting out standard include files, like and in the main pulse program wouldn't interfere with the simulation (see the examples provided). If the content of your include file (other than these mentioned above) is important for your pulse program, you might want to copy and paste it in the body of the pulse program prior to translating it. Frequency switch is not implemented yet. Also frequency offset for a shaped RF pulse is not currently available. Phase list must contain ONE line per phase, e.g. ph31=0 or ph31=0 2 2 0 2 0 0 2 2 0 0 2 0 2 2 0 but not ph31=0 2 2 0 2 0 0 2 2 0 0 2 0 2 2 0 Please make sure that the first line in the list of the actual pulse program commands begins with a label, e.g. 1 ze or 1 d11 ze even if this label is not used for loops or go= statemets. Any positive integer or 0 will work. If the first line contains a single ze command with no label, the program will recognize it and automatically insert a 0-label: 0 ze, but more complicated cases (e.g. d11 ze) might not be translated properly. Call for volunteers: Anyone of VARIAN-users who would like to participate (directly or advising) in making a translator for Varian pulse sequences??? (I have no experience with Varian) Note for Norton Antivirus users: In the past I encounted some problems running Xlate with Norton AV virus scan enabled on Win98SE or Win95 PC's: Malab hung up when I tried to execute Xlator. This problem happened to be known to Matlab people and caused by some unresolved Matlab problem of executing dos(' ') commands under Win98SE/95 with virus scan enabled. Matlab's customer support suggested disabling the virus scan -- and it did help. The good news is that you only have to do it only once -- during the installation. You can enable NAV after that. I haven't seen this problem on Win2000 or NT. Other antivirus software (I switched to McAffee) works fine. Note for UNIX/Linux users: The installation of the Xlator is now fully performed under Matlab. It should run as snoothly as under Windows. Also, you have to make sure that you have all necessary write-permissions in the corresponding folders. Note for Mac users: I haven't tested the package on a Mac (sorry, I don't have one). Since it runs under Matlab, theoretically, there should be no problem with it, but I would really like to know if this is the case. 2. RELAXATION CALCULATOR (in the spin setup panel). This function allows you to calculate relaxation rates given dynamic properties of the system. 1) The equations used for calculating R1-matrix and its implementation for spin relaxation during experiment require some corrections, so the use of R1 matrix is not recommended, temporarily. 2) While the Relaxation Calculator doesn't care how many spins are in your spin system (only the two checked out spins are considered), the simulator does seem to care. Use R2-matrix ONLY for a 2-spin system!!! 3. RELAXAITON TREATMENT: currently the same relaxation rate is applied to both Sx and 2SxIz components. The relax rate for 2SzIz is set as the sum of relaxation rates for Iz and Sz. 4. MULTIPLE CHANNELS: The program supports up to a 4-channel experiment. If two or more channels are assigned to the same type of nucleus, only the first of these channels (the one with the smallest channel number, i.e. the top one on the list) can have carrier position (Op) set to a non-zero number. Otherwise you can get artifacts in your simulated spectra. For example, since only 3 nuclei are currently implemented, inevitably two of the channels will be tuned to the same nucleus: by default, 1H is on both Ch.1 and Ch.4). If you use this setting, make sure that the carrier position for Ch.4 is set to 0. 5. Simulating multichannel experiments with two or more channels tuned to the same type of nucleus has some limitations in the current version. If you have selected (in the Experimetnal Setup) the same type of nucleus (e.g. 1H) for more than one channel, only one of these channels (the top one i.e. the one with the smallest channel #) can have its carrier position (Op) set to a nonzero offset. You MUST set the Op values to 0 for the rest of these channels. This limitation does not apply to a single channel tuned to a particular type of nucleus. 6. DECOUPLING is currently done explicitly, by applying a tray of 'exact' 180- degree pulses. More sophisticated decoupling sequences, like WALTZ, MLEV, etc, are to be included. 7. Please keep in mind that whenever you change the dimension of your experiment, the simulation will not run until you Xlate the pulse program and set program parameters. The experimental setup window will be updated automatically, while the data processing window and data processing parameters will not change untill you run a new simulation. This is done in order to allow you to process and analyze the already "acquired" data set. The same applies when you import data from XWINNMR. 8. GRADIENTS: simulating an experiment with pulsed-field gradients takes more time than for a non-gradient experiment. Therefore it is recommended that those gradients that are not necessary for coherence selection (for example purge gradients) are being removed (commented out) from the pulse sequence before its translation. 9. The simulated data set (vs_runCalc.ser0) is a 2D matrix with tdin complex points in the "incremented" dimension and tdaq points in the "acquisition" dimension, its total size is (tdin x tdaq). These parameters are automatically set to the following values (in the Program Params window): tdin = td1 and tdaq = td2 for a 2D experiment; tdin = 1 and tdaq = td1 for a 1D experiment; tdin = td1*td2 and tdaq = td3 in the 3D case. You can change these settings in the Program Params window. 10. 3D: We have recently added the capability to simulate, process, and visualize 3D experiments. While 1D and 2D capabilities had been extensively tested, the 3D part is still in testing and development. Please email me your suggestions and bugs and/or discrepancies with experiment. Because a 3D data set requires more space in the memory, internal data assignment in Matlan after the 3D processing might require 1-2 seconds. It is recommended that you wait till a message "3D processing complete" appears in Matlab window, before opening 3D Spectrum Display windows. 11. Interfaces with XWINMR and NMRPipe. The interfaces are now working for 1D and 2D data. 3D functionality is under testing and has been temporarily disabled. When opening your spectrum in XWINNMR first time, you might see a message saying that some files required for data display are missing -- simply ignore this message, and XWINNMR will create all necessary files automatically. While the interface with XWINNMR has been extensively tested in both directions (i.e. export to and import from, including data processing and visualization), export to NMRPipe has not been fuly tested. If you find out that some parameters/settings are not being properly transfered, please let me know. 12. Compatibility with Matlab versions. The program works under 6.1 (Release 12), and 6.5 (Release 13). It should work under 6.0, but I haven't fully tested it (as I haven't version 6.0 available) -- let me know if you run into any problems. NOTES for Matlab 5.3 users: Although all effort was made to make VNMR fully compatible with an earlier version, Matlab 5.3 (Release 11), there could be some issues that we have overlooked. It is most likely that you will need to recompile the Translator, see Installation instructions. Also, in the folder "converters" you will find a file vs_dqdfix_53.p that contains instructions for dealing with Bruker digital filtered data. If you want to be able to import XWINNMR data, you need to copy this file into the same directory as vs_dqdfix.p (i.e. overwrite the existing file vs_dqdfix.p which was compiled for 6.? version). In the same directory, there is also a file called vs_dqdfix_61.p -- you will need it if you want to switch back to Matlab 6.? -- just copy it over dqdfix.p If you find any problems with running VNMR under Matlab 5.3 please let me know. Due to the use of cell arrays, structures etc in the current VNMR version, it might not run properly on earlier (now probably considered ancient) versions of Matlab (4.0 and 4.2). 13. Compatibility with various OS. We tested the program on Windows (95, ME, 2000, XP) and on Linux (Red Hat 8??, Gentoo, Mandrake). I haven't recently tried it on UNIX and I never tried it on a Mac. If you are using these OS, please let me know if you have problems. 14. Last but not least. The VNMR program was written and modified over the course of several years. In addition, during this time, Matlab as programming environment underwent significant modifications, from the earlier version 4.2 up to the newest 6.5 version. No wonder that the VNMR code is somewhat 'patchy'. Well, one day we will have to rewrite it into a more compact and self-consistent code. Volunteers? >>>>>>>>>>>> last updated Feb. 2, 2004 <<<<<<<<<<<<<<<