source: sasview/sasview/README.txt @ 40c69b3

ESS_GUIESS_GUI_DocsESS_GUI_batch_fittingESS_GUI_bumps_abstractionESS_GUI_iss1116ESS_GUI_iss879ESS_GUI_iss959ESS_GUI_openclESS_GUI_orderingESS_GUI_sync_sascalccostrafo411magnetic_scattrelease-4.1.1release-4.1.2release-4.2.2release_4.0.1ticket-1009ticket-1094-headlessticket-1242-2d-resolutionticket-1243ticket-1249ticket885unittest-saveload
Last change on this file since 40c69b3 was 40c69b3, checked in by pkienzle, 9 years ago

update the docs for build from source

  • Property mode set to 100644
File size: 19.7 KB
Line 
1Release Notes
2=============
3
41- Features
5===========
6
7   - New in Version 3.1.1
8     --------------------
9     - Fixes bug #457 that prevented SasView from starting if the user was not
10       connected to the internet, or was behind a proxy server.
11
12   - New in Version 3.1.0
13     --------------------
14     - The documentation/help has had a complete overhaul including:
15       - A completely new presentation interface (Sphinx).
16       - Proof reading!
17       - Updating for latest features.
18       - A Help (or sometimes ?) button has been added to every panel, and some
19         sub panels if appropriate, linking to the appropriate section in the
20         documentation.
21       - The model help has been split so that the Details button now brings up
22         a very short pop-up giving the equation being used while HELP goes to
23         the section in the full documentation describing the model.
24       - Extensive help has also been added for the new optimizer engine (see
25         below) including rules of thumb on how and when to choose a given
26         optimizer and what the parameters do.
27     - The optimizer engine has been completely replaced. The new optimizer
28       still defaults to the standard Levenberg-Marquardt algorithm. However 4
29       other optimizers are now also available. Each starts with a set of default
30       parameters which can be tuned. The DREAM optimizer takes the longest but
31       is the most powerful and yields rich information including full parameter
32       correlation and uncertainty plots. A results panel has been added to
33       accommodate this.
34       - The five new optimizers are:
35         - A Levenberg-Marquardt optimizer
36         - A Quasi-Newton BFGS optimizer
37         - A Nelder-Mead Simplex optimizer
38         - A Differential Evolution optimizer
39         - A Monte Carlo optimizer (DREAM)
40     - New models were added:
41         - MicelleSphCoreModel (currently residing in the Uncategorized category)
42     - Existing models were updated:
43         - LamellarPS (bug in polydispersity integration fixed)
44         - RectangularPrismModel
45         - RectangularHollowPrismModel
46         - RectangularHollowPrismInfThinWallsModel
47     - Infrastructure to allow SESANS data to be fit with models was added. This
48       will become available in a future release but can currently be used from
49       the command line with some caveats.
50     - A number of bugs were fixed including a thread crashing issue and an
51       incorrect slit smearing resolution calculation.
52     - Implemented much more robust error logging to enable much easier
53       debugging in general but particularly the debugging of issues reported by
54       SasView users.
55     - A number of infrastructure tasks under the hood to enhance maintainability
56     - Upgrade from Wx 2.8 to Wx 3.0.2 which allows several new features but
57       required significant additional rework as well.
58     - Fully implemented Sphinx to the build process to produce both better
59       user documentation and developer documentation.
60     - Restructuring of the code base to more unified nomenclature and structure
61       so that the source installation tree more closely matches the installer
62       version tree.
63     - Code cleanup (an ongoing task) .
64     - Migration of the repository to github simplifying contributions from
65       non-project personnel through pull requests.
66
67   - New in Version 3.0.0
68     --------------------
69     - The GUI look and feel has been refactored to be more familiar for
70       Windows users by using MDI frames. Graph windows are also now free-
71       floating.
72     - Five new models have been added: PringlesModel, CoreShellEllipsoidXTModel,
73       RectangularPrismModel, RectangularHollowPrismModel and
74       RectangularHollowPrismInfThinWallsModel.
75     - The data loader now supports ILL DAT data files and reads the full meta
76       information from canSAS file formats.
77     - Redefined convention for specifying angular parameters for anisotropic
78       models.
79     - A number of minor features have been added such as permitting a log
80       distribution of points when using a model to simulate data, and the
81       addition of a Kratky plot option to the linear plots.
82     - A number of bugs have also been fixed.
83     - Save Project and Save Analysis now work more reliably.
84     - BETA: Magnetic contrast supporting full polarization analysis has been
85       implemented for some spherical and cylindrical models.
86     - BETA: Two new tools have been added:
87       - A generic scattering calculator which takes an atomic, magnetic or
88         SLD distribution in space and generates the appropriate 2D
89         scattering pattern. In some cases the orientationally averaged
90         (powder) 1D scattering can also be computed. Supported formats
91         include: SLD or text, PDB, and OMF magnetic moment distribution
92         file.
93       - An image viewer/converter for data in image format; this reads in
94         an image file and will attempt to convert the image pixels to
95         data. Supported formats include: TIFF, TIF, PNG, BMP, JPG.
96
97   - New in Version 2.2.1
98     --------------------
99     - Minor patch to support CanSAS XML v1.1 file format
100     - Added DataInfo for data in the DataExplorer and plots
101     - Added Maximize/Restore button in the title bar of the graphs
102     - Added a hide button in the toolbar of the graph panel
103     - The 'x' button now deletes a graph
104     - Edit SUM Model from the menubar can now generate and save more than one sum model
105     - Reports can now be saved in pdf format on WIN and MAC
106     - Made significant improvements to the batch/grid panel and fixed several bugs
107     - Fixed a number of other minor bugs
108
109   - New in Version 2.2.0
110     --------------------
111     - Application name changed to SasView
112     - New fully customizable Category Manager added for better management of
113       increasing number of models
114     - Improved the Grid Window functionality in the batch fitting mode
115     - Added a simpler Graph/Plot modification interface
116     - Added a new 'Data Operation' tool for addition, subtraction, multiplication,
117       division, of two data sets.
118     - The 'Sum Model' editor was extended and renamed 'Summation and Multiplication'
119       editor
120     - Added more plot symbols options for 1d plots
121     - Added improved trapping of compiling errors to the 'New model editor'
122     - Added some intelligent outputs (e.g., Rg, background, or rod diameter
123       depending on the choice of axis scale of the plot) to the linear fits
124     - Added more models
125     
126   - Feature set from previous versions         
127     -----------------------------------
128     - Perspectives Available
129       - Invariant calculator: Calculates the invariant, volume fraction, and
130         specific surface area.
131       - P(r) inversion calculator: Indirect Fourier transformation method.
132       - Fitting: the tool used for modeling and fitting 1D and 2D data to
133         analytical model functions
134       - Tools: provides a number of useful supplementary tools such as SLD
135         calculation 
136   
137     - Fitting
138       - Includes a large number of model functions, both form factors and structure factors.
139       - Support P(Q)*S(Q) for form factors that flag they can be so multiplied.
140       - Supports Gaussian, lognormal, Shulz, rectangular and custom distribution
141         functions for models that need to include polydispersity or for orientational
142         distributions if appropriate.
143       - Anisotropic shapes and magnetic moment modeling in 2D allow for a non-uniform
144         distribution of orientations of a given axis leading to modeling and fitting
145         capabilities of non azimuthaly symmetric data. 
146       - User can choose to weight fits or not. If using weights, the user can choose
147         the error bar on each point if provided in the file, the square root
148         of the intensity or the intensity itself.
149       - Instrumental resolution smearing of model or fits is provided with several
150         options: read the resolution/point fromt he file. Input a pinhole resolution
151         or a slit resolution.
152       - Users can define the Qrange (Qmin and Qmax) for both 1D and 2D data for
153         fitting and modeling, but not graphically.  The range can be reset to the
154         defaults (limits of q in data set for a fit) with the reset button.
155       - A mask can be applied to 2D calculation and fitting.
156       - Normalized residual plots are provided with every fit.
157       - Model function help available through detail button or from the fitting panel.
158       - Simultaneous/(advanced)constrained fitting allows for fitting a single
159         data set or several different sets simultaneously with the application
160         of advanced constraints relating fit parameters to functions of other
161         parameters (including from a different set). For example thickness of
162         shell = sin(30) times the length. 
163       - Models that are the sum of two other models can be easily generated through the
164         SUM Model menubar item.
165       - New Python models can be added on the fly by creating an appropriate Python
166         file in the model plugin directory. Two tools are provided to help:
167         An easy to use custom model editor allows the quick generation of new Python
168         models by supplying only the parameters and their default value (box 1)
169         and the mathematical function of the model (box 2) and generating the
170         necessary *.py file.  A separate advanced model editor provides a full Python
171         file editor.  Either way once saved the model becomes immediately available
172         to the application.
173       - A batch fitting capability allows for the analysis of a series of data sets to
174         a single model and provides the results in a tabular form suitable for saving
175         or plotting the evolution of the fit parameters with error bars (from within
176         the application).
177 
178     - Tools
179       - A scattering length density calculator,including some X-ray information
180         is provided.
181       - A density to vol. fraction converter is provided
182       - In application access to a Python shell/editor (PyCrust) is provided
183       - An instrument resolution calculator, including possible gravitational and
184         TOF effects is provided
185       - A slit size calculator optimized for Anton Paar Saxess is provided.
186       - A kiessig fringe thickness calculator is provided
187         
188     - Plots and plot management
189       - A 3D graphing option (for 2d data/results) is provided with the view
190         controlled by the mouse
191       - 2D plots are shown with an intensity color bar. 2D Color map can be user
192         adjusted.
193       - Supports output of plot to a variety of graphic formats. Supported formats
194         include: png, eps, emf, jpg/jpeg, pdf, ps, tif/tiff, rawRGBbitmap(raw, rgba),
195         and scalable vector graphic (svg/svgz)
196       - Supports ouput of data in plot (1 or 2D) to limited data formats
197       - Multiple data sets can be loaded into a single graph for viewing (but a fit
198         plot can currently only have a single plot).
199       - Extensive context sensitive plot/fitting/manipulation options are available
200         through a right mouse click pop-up menu on plots.
201           
202     - Data management
203       - Supports 2 + column 1D ASCII data, NIST 1D and 2D data, and canSAS data
204         via plug-in mechanism which can easily allow other readers as appropriate.
205       - 2D data is expected in Q space but for historical reasons accepts the
206         NIST 2D raw pixel format and will do conversion internally.
207       - The full data and metadata available to SasView is viewable in ASCII via
208         right clicking on a data set and choosing Data Info in the DataExplorer
209         or on the plots
210       - Supports loading a single file, multiple files, or a whole folder   
211       - An optional Data Explorer is provided (default) which simplifies managing,
212         plotting, deleting, or setup for computation. Most functions however do
213         not require access to the explorer/manager and can be accessed through
214         right click menus and the toolbar.  The data explorer can be re-started
215         from the menu bar.
216           
217     - Data manipulation
218       - Support various 2D averaging methods : Circular, sectors, annular,
219         boxsum, boxQx and boxQy.
220       - A 2D data maks editor is provided
221       - 2D mask can be applied to the circular averaging.
222         
223     - Miscellaneous features
224       - limited reports can be generated in pdf format
225       - Provides multiprocessor support(Windows only)
226       - Limited startup customization currently includes default startup
227         data folder and choice of default starting with data manager
228       - Limited support for saving(opening) a SasView project or a SasView analysis
229         (subproject) is provided.
230       - SasView can be launched and loaded with a file of interesty by double-clicking
231         on that file (recognized extension)
232       - A data file or data folder can be passed to SasView when launched from
233         the command line.
234       - Limited bookmarking capability to later recall the results of a fit calculation
235         is provided.
236       - Extensive help is provided through context sensitive mouse roll-over,
237         information bar (at the bottom of the panel), the console menu, and
238         access to the help files in several different ways.
239
240
2412- Downloading and Installing
242=============================
243       
244   *** Note 1:  Much more information is available at www.sasview.org under links.
245                    Look in the 'For Developers' section and particularly the wiki at
246                www.sasview.org/trac/wiki.
247   *** Note 2:  If you have EXE or ZIP SasView installer, you won't need any of
248                the following.  However it is highly recommended that any
249                previous versions be un-installed prior to installing the
250                new version.
251
252   2.1- System Requirements
253        - Python version >= 2.5 and < 3.0 should be running on the system
254        - We currently use Python 2.7
255
256   2.2- Installing from source
257        - Get the source code
258          - to follow the current development version from source control use
259              git clone https://github.com/SasView/sasview.git
260              git clone https://github.com/bumps/bumps.git
261          - to install a specific version
262
263        - Build, install and run a specific release
264          - make sure the requirements below are already installed
265          - retrieve the source from https://github.com/SasView/sasview/releases
266          - open a command line window in the 'sasview-x.x.x' directory
267          - run 'python setup.py install'
268          - run 'python sasview.py' under the 'sasview' folder.
269
270        - Build, install and run the current development version
271          - clone the source from git; also clone bumps, which is developed in parallel
272              git clone https://github.com/SasView/sasview.git
273              git clone https://github.com/bumps/bumps.git
274          - open a command line window in the 'sasview' directory
275          - run 'python setup.py build'
276          - run 'python run.py'; this runs from the source directories, so you
277            don't have to rebuild every time you make a change, unless you are
278            changing the C++ model files
279
280        - The following modules are required (version numbers are what are used
281          in the windows release build):
282         
283          - Common Packages
284            - reportlab 3.1.44
285            - lxml 3.4.4.0 (MAC 3.4.2.0)
286            - PIL 1.1.7
287            - xhtml2pdf 3.0.33 (MAC = not installed on build server)
288            - unittest-xml-reporting 1.12.0 (MAC 1.10.0)
289            - matplotlib Version Installed: 1.4.3 (MAC 1.1.1)
290            - bumps Version Installed: 0.7.5.6
291            - scipy Version Installed: 0.16.0b2 (MAC 0.11.0)
292            - periodictable Version Installed: 1.4.1
293            - setuptools Version Installed: 7.0 (MAC 12.0.5)
294            - sphinx Version Installed: 1.3.1 (MAC 1.3b2)
295            - pyparsing Version Installed: 2.0.3
296            - numpy Version Installed: 1.9.2 (MAC 1.6.2)
297            - html5lib Version Installed: 0.99999
298            - wx Version Installed: 3.0.2.0
299         
300          - Windows Specific Packages
301            - pywin 219
302            - py2exe 0.6.9
303            - comtypes 1.1.1
304            - MinGW w/ gcc version 4.6.1 (WIN)
305            - vcredist_x86.exe (version 9.0.21022.8  -microsoft visual C 2008
306              re-distributable)
307            - Innosetup (WIN - isetup 5.4.2-unicode) - used to create distributable
308
309            *** Note: Windows build dependencies can be set up using anaconda. Instructions
310                can be found at http://trac.sasview.org/wiki/AnacondaSetup
311           
312          - MAC Specifc Packages
313            - py2app 0.7.1
314         
315
3163- Known Issues
317===============
318
319   3.1- All systems:
320        - The documentation window may take a few seconds to load the first time
321          it is called. Also, an internet connection is required before
322          equations will render properly. Until then they will show in their
323          original TeX format.
324        - If the documentation window remains stubbornly blank, try installing a
325          different browser and set that as your default browser. Issues have
326          been noted with Internet Explorer 11.
327        - Check for Updates may fail (with the status bar message ' Cannot
328          connect to the application server') if your internet connection uses
329          a proxy server. Tested resolutions for this are described on the
330          website FAQ.
331        - The copy and paste functions (^C, ^V) in the batch mode results grid
332          require two clicks: one to select the cell and a second to select the
333          contents of the cell.
334        - The tutorial has not yet been updated and is somewhat out of date
335        - Very old computers may struggle to run the 3.x and later releases
336        - Polydispersity on multiple parameters included in a simultaneous/
337          constrained fit will likely not be correct
338        - Constrained/simultaneous fit page does not have a stop button
339        - Constrained/simultaneous fit do not accept min/max limits
340        - Save project does not store the state of all the windows
341        - Loading projects can be very slow
342        - Save Project only works once a data set has been associated with
343          a model.  Error is reported on status bar.
344        - There is a numerical precision problem with the multishell model when
345          the iner radius gets large enough (ticket #288)
346        - The angular distribution angles are not clearly defined and may in
347          some cases lead to incorrect calculations(ticket #332)
348         
349   3.2- Windows:
350        - If installed to same directory as old version without first removing
351          the old version, the old desktop icon will remain but point to the
352          new exe version. Likewise all the start menu folders and items will
353          have the old name even though pointing to the new version.  Usually
354          safest to uninstall old version prior to installing new version anyway.
355               
356   3.3- MAC:
357        - Application normally starts up hidden. Click icon in Dock to view/use
358          application.
359        - Multiprocessing does not currently work on MAC OS
360               
361   3.4- Linux:
362        - Not well tested
363
364
3654- SasView website
366==================
367
368   - www.sasview.org.  This main project site is the gateway to all
369     information about the sasview project.  It includes information
370     about the project, a FAQ page and links to all developer and user
371     information, tools and resources.
372
373
3745- Frequently Asked Questions
375=============================
376
377   - www.sasview.org/faq.html
378
379
3806- Installer download website
381=============================
382
383   - Latest release Version
384     - https://github.com/SasView/sasview/releases
385   - Latest developer builds
386     - https://jenkins.esss.dk/sasview/view/Master-Builds/
387
388   
Note: See TracBrowser for help on using the repository browser.