====== Sample Builder ======

{{ :wiki:screenshot_samplebuilder.png?direct&400 |}}

===== Preface =====

This brief manual was written for participants of ETH/EPFL Summer School 2026: Optical Probing of Nanomaterials in- and out-of-Equilibrium (OPNEq). I am copy pasting it here, but it will develop into more detailed wiki.

===== Warnings about some issues =====

There are few things that do not work very well or work well but we will avoid them for now.

==== Scaling ====

The Windows UI scaling of Sample Builder is not very good. I always use 125% “custom” scaling in windows, which renders the UI as designed. Different scaling factors in Windows will make trouble for some UI elements, they might appear too large, too small, overlapping, or unreadable. This is supposedly going to be fixed in QBerr 3.

==== Menus invisible ====

Another glitch of the older Qt framework is that the UI can respond weirdly, if the program remains open over longer period of time, typically days, but sometimes even after few hours. Most obvious manifestation of this problem is that the standard window menus are not rendered on the screen, while still actually appearing invisibly. 

==== Point by point and parameterized fitting ====

This problem is related to fitting model to data. One **should not** fit point-by-point feature together with parameterized peaks. The fit will start optimizing in huge parameter space, which will take long time, even the first iteration can take minutes before the fit can be aborted.

==== Multi-sample analysis ====

This is not really an issue, just warning about hidden complexity. One of the strengths of Sample Builder is so-called multi-sample analysis, and it is something we will not cover in this brief introductory manual. What it means is that we can build multiple sample models, which will have the same structure, just differ in parameters (e.g. temperature dependent experiment on single sample). We do not need that for basic sample fitting, but the functionality appears in many parts of the UI. In some cases, fitting large multi-sample to large datasets might lead to crashes.

==== Crashes ====

Normally the Sample Builder does not crash. It might crash on public demos.

===== Files and formats =====

The program itself is a compiled executable **SampleBuilder.exe**. It will want to locate a configuration file **SampleBuilder.inpx** in the same folder. We should also have **default.sample** file in the same folder but do not need it necessarily. The sample model is stored as **.sample** file, which is xml container for the model structure and parameters. The default format for data is **.epdx**, which is again xml container for raw numeric data and experiment metadata.

===== Overview of UI and components =====

Main parts of the UI are:

==== Main window ====

This is where all the structure and parameters of the sample can be edited. Contains also text output panel.

==== Data manager (dataman) ====
 
Dataman is accessed from the main menu item //Experiment//. It is possible to load any number epdx data files to sample builder even if they are not being analyzed.  Dataman stores all the available files, and can also be used for editing metadata, or manipulating the data – enhancing, trimming, merging, differentiating etc.

==== Plot windows ====

User can open any number of results and simulation plot windows, with different kind of quantities. The plot windows are accessible from the main menu //Experiment//. Windows can be closed but will still keep their state and can be later reopened from menu //Experiment>View//. No calculation is done for closed windows. Completely unwanted windows can be killed from the main menu //Experiment>Kill//.

There are 2 types of plot windows: 

//Model plot//

Shows only the individual dielectric function models, not a simulated experiment.

//Experiment plot//

Different kinds of simulated quantities (Psi Delta, Mueller matrix, Reflectivity, etc.), taking into account the whole optical layer model. 

===== Sample structure =====

The main window UI elements and also the main menu follow the structure of the Sample model, which is internally a tree of objects, like Layers, Materials, Models, spectral Features and individual Parameters.

FIXME
===== Material =====

===== Model =====

===== Feature =====