Adding a field to an application

In this example, we'll add the Use Numerical Integration Method field to the Partially Coherent Intensity Report in the SRW application.

The field is a boolean (0, 1) and should be shown on the main editor page for the report. Selecting the toggle should set this flag in the generated code:

['wm_am', 'i', 1, 'multi-electron integration approximation method: 0- no approximation (use the standard 5D integration method), 1- integrate numerically only over e-beam energy spread and use convolution to treat transverse emittance'],

Adding the field requires updating the srw-schema.json file which contains the field definition of the models (e.g., electronBeam, undulator, intensityReport) and the field layout of the views (model editors). The schema is used on both the client (javascript) and on the server (python).

In the srw-schema.json, we'll add the "MultiElectronIntegrationMethod" enum and the "integrationMethod" field below. The parameters are (field-name: [label, field-type, default-value, help-text]).

"enum": {
    ...
+   "MultiElectronIntegrationMethod": [
+       ["0", "No approximation (use the standard 5D integration method)"],
+       ["1", "Integrate numerically only over e-beam energy spread and use convolution to treat transverse emittance"]
+   ],

"model": {
    ...
    "multiElectronAnimation": {
        "stokesParameter": ["Representation of Stokes Parameters", "StokesParameter", "0"],
        "numberOfMacroElectrons": ["Number of Macro-Electrons", "Integer", 100000, "Number of macro-electrons (coherent wavefronts) for calculation of multi-electron wavefront propagation"],
+       "integrationMethod": ["Use Numerical Integration Method", "MultiElectronIntegrationMethod", "0"],
        "intensityPlotsWidth": ["Maximum Plot Width [pixels]", "IntensityPlotsWidth", "0"],
        "intensityPlotsScale": ["Plot Scale", "IntensityPlotsScale", "linear"],
        "photonEnergyBandWidth": ["Photon Energy Band Width [eV]", "Float", 0],
        "colorMap": ["Color Map", "ColorMap", "grayscale"]
    },

Also in srw-schema.json, we'll add the "integrationMethod" field to the multiElectronAnimation view. The "advanced" section contains the fields which appear when the pencil icon is selected for the report. In this case, there are three tabs, named Main, Scale and Other. We'll add the "integrationMethod" after the "numberOfMacroElectrons" fields on the Main tab.

"multiElectronAnimation": {
    "title": "Partially Coherent Intensity Report",
    "basic": [],
    "advanced": [
        ["Main", [
            "simulation.photonEnergy",
            "stokesParameter",
            "numberOfMacroElectrons",
+           "integrationMethod",
            "photonEnergyBandWidth"
        ]],
        ["Scale", [
            "intensityPlotsWidth",
            "intensityPlotsScale"
        ]],
        ["Other", [
            "colorMap"
        ]]
    ]
},

This diagram above shows the relationship between the schema and the UI components. The sirepo javascript framework will take the schema definition an automatically create the UI elements for editing the values. If additional UI logic is required, such as showing/hiding values based on the model values, then application code would be added to srw.js.

On the server side, the template/srw.py module uses the schema and a jinja template to generate the python code which will be executed. In this case, the only change is to update the package_data/template/srw/parameters.py.jinja file with the new field:

    ['wm_ei', 'i', {{multiElectronAnimation_photonEnergyIntegration}}, 'integration over photon energy is required (1) or not (0); if the integration is required, the limits are taken from w_e, w_ef'],
    ['wm_rm', 'i', 1, 'method for generation of pseudo-random numbers for e-beam phase-space integration: 1- standard pseudo-random number generator, 2- Halton sequences, 3- LPtau sequences (to be implemented)'],
+   ['wm_am', 'i', {{multiElectronAnimation_integrationMethod}}, 'multi-electron integration approximation method: 0- no approximation (use the standard 5D integration method), 1- integrate numerically only over e-beam energy spread and use convolution to treat transverse\
 emittance'],
    ['wm_fni', 's', '{{multiElectronAnimationFilename}}', 'file name for saving propagated multi-e intensity distribution vs horizontal and vertical position'],

View the GitHub commit with this change.