================== Analysis ================== ESonix features three kind of analysis: * Regular * Combination * Sensitivity * Batch In addition to the analysis, the `Tweaks` facility is also available. .. _create_regular_runs: Regular runs ============ Regular runs are the basic analysis in ESonix. Once a project features several regular runs, the user can perform combination or sensitivity analysis on the top of them. Model Initialisation -------------------- Once the model is uploaded on the ESonix Server, ESonix will perform several steps before triggering the run. This phase is called "Initialisation" and is described in :numref:`model_initflow`. .. _model_initflow: .. figure:: fig/initflow.png :align: center :alt: model initialisation :figclass: align-center :class: screenshot :width: 400pt Regular Run Model Initialisation Flow Graph Preparation ----------- A `regular run` is prepared and run from its father project by clicking on the ``new run``, button as shown in :numref:`blank_project`. The "new run" form is pre-filled with parameters defined during the Project creation (:ref:`create_project_phase`). Model parameters """""""""""""""" .. _new_run_basic_parameters: .. figure:: fig/new_run_00.png :align: center :alt: new run basic parameters :figclass: align-center :class: screenshot :width: 500pt New run model parameters Form Model parameters are (numbers refer to :numref:`new_run_basic_parameters`): 1. ``Model``: Button to browse and attach the XLS/XLSX model file to run. 2. :ref:`Model's Units system `. 3. :ref:`Doors Configuration to run `. 4. :ref:`Load Cases to run `. Default (blank) is A 5. :ref:`params_sub-modelling_zone`. 6. ``Comments``: Free text. If blank, ESonix will fill it with miscellaneous data. Runtime Parameters """"""""""""""""""" .. _new_run_runtime_parameters: .. figure:: fig/new_run_01.png :align: center :alt: new run advanced parameters :figclass: align-center :class: screenshot :width: 500pt New run runtime parameters Form Runtime parameters are (numbers refer to :numref:`new_run_runtime_parameters`): 1. :ref:`Thermodynamical model (or engine) `. 2. :ref:`Simulation time Step `. 3. :ref:`Simulation sampling `. 4. :ref:`params_write_data_on_event`. 5. :ref:`Simulation timeout `. 6. :ref:`Simulation Convergence Criteria `. 7. :ref:`params_post-convergence_margin`. Runtime advanced Settings """""""""""""""""""""""""" .. _new_run_runtime_advanced_settings: .. figure:: fig/new_run_02.png :align: center :alt: new run advanced parameters :figclass: align-center :class: screenshot :width: 500pt New run runtime advanced Form Runtime advanced parameters are (numbers refer to :numref:`new_run_runtime_advanced_settings`): 1. :ref:`params_adaptive_strategy` 2. :ref:`params_adaptive_strategy_max_co_target` 3. :ref:`params_adaptive_strategy_neighborhood_zone` 4. :ref:`params_adaptive_strategy_max_co_ramp` 5. :ref:`params_default_opening_latency` 6. :ref:`params_raw_merging` Launch and evolution of the run ------------------------------- Once ``Go!`` button is pressed, the spreadsheet is sent to the ESonix server, with the relevant parameters. The spreadsheet is preprocessed and checked. If it contains no errors, calculation is automatically fired. .. _combination_analysis: Combination Analysis ==================== Combination analysis provides a mean to *combine* some regular existing nodes. It can be run by clicking on the ``Combination`` button as shown in :numref:`combination_run`. Combination will build a single set of result based on the provided existing nodes. For example, in the :numref:`combination_run` the Node **A6** is a combination between Nodes A4 and A5. .. _combination_run: .. figure:: fig/new_combination_run.png :align: center :alt: new run advanced parameters :figclass: align-center :class: screenshot :width: 500pt Combination Run Access To do so, ESonix will begin by creating a load case mapping. This mapping will renumber existing load cases to avoid clash between models. For example, a combination made of three nodes would be mapped as follows: .. _combination_example_table: .. table:: Example of Combination Laod Cases mapping +--------------------+---------+------------+ | combined Load Case | Node ID | LodCase ID | +====================+=========+============+ | 1001 | A1 | 1001 | +--------------------+ +------------+ | 1002 | | 1002 | +--------------------+ +------------+ | 1003 | | 1003 | +--------------------+---------+------------+ | 1004 | A2 | 1001 | +--------------------+ +------------+ | 1005 | | 1002 | +--------------------+---------+------------+ | 1006 | A3 | 1001 | +--------------------+ +------------+ | 1007 | | 1018 | +--------------------+---------+------------+ This can be read as follows: Load Case 1005 for node A4 (combination of A1, A2 and A3) is actually load case 1002 from Node A2. Once mapping is done, post-processing is performed in the same way as regular runs. All the tools available for regular runs are available for combination nodes, including sensitivity. Opening in Cabin are usually checked with an empty cargo, such as an important mass of air is available in the cargo to be discharged into the cabin. At opposite, when checking an explosion in the cargo itself, it will be more conservative to assume a cargo occupied. :numref:`combination_example` is extracted from :ref:`tuto4` illustrates the latter example. .. _combination_example: .. figure:: fig/sketch_combination_analysis.png :width: 400pt :align: center :alt: Combination analysis examle :figclass: align-center Combination Analysis example The example illustrated :numref:`combination_example` could be addressed by combining two models: one with empty Cargo, one with occupied cargo. The first model would feature load cases for explosions in the main deck only (thus, volumes 1, 2 and 3), while the second one would feature explosion in the cargo (volume 4). The Load Case Mapping would then look like :numref:`combination_example_table2`. .. _combination_example_table2: .. table:: Load Cases mapping relative to :numref:`combination_example` +--------------------+---------+------------+--------------+ | combined Load Case | Node ID | LodCase ID | explosion in | +====================+=========+============+==============+ | 1001 | A1 | 1001 | vol. 1 | +--------------------+ +------------+--------------+ | 1002 | | 1002 | vol. 2 | +--------------------+ +------------+--------------+ | 1003 | | 1003 | vol. 3 | +--------------------+---------+------------+--------------+ | 1004 | A2 | 1001 | vol. 4 | +--------------------+---------+------------+--------------+ .. seealso:: More details about combination analysis may be found in :ref:`tuto4`. .. _sensitivity_analysis: Sensitivity Analysis ==================== The sensitivity analysis gives the possibility to compare results between Nodes or between a Node and an external file. It can be run by clicking on the ``Sensitivity`` button as shown in :numref:`sensitivity_run`. For example, in the :numref:`sensitivity_run` the Node **A8** is a result of a sensitivity analysis between Nodes A6 and A7. .. _sensitivity_run: .. figure:: fig/new_sensitivity_run.png :align: center :alt: new run advanced parameters :figclass: align-center :class: screenshot :width: 500pt Sensitivity Run Access After clicking on ``Sensitivity`` button as per :numref:`sensitivity_run`, the models need to be selected in the "Sensitivity Analysis Form" as per :numref:`sensitivity_form_fig`. .. _sensitivity_form_fig: .. figure:: fig/sensitivity_form.png :align: center :figclass: align-center :width: 400pt :class: screenshot :alt: Sensitivity analysis form Sensitivity Analysis Form Sensitivity parameters are (numbers refer to :numref:`sensitivity_form_fig`): 1. ``Reference Node``: Selection of the Node of reference. 2. ``Nodes to Combine``: Selection of one or more nodes to be investigated. 3. ``Browse``: option to run sensitivity analysis with external file (.xls/.xlsx). The 'External File' must be written as per a simple template as explained in (:ref:`external_reference_file`). .. seealso:: More details about sensitivity analysis may be found in :ref:`tuto4`. .. _batch_analysis: Batch Analysis ==================== The Batch analysis gives the possibility to: * Run several Nodes in parallel. * Enable easy parametric studies to check, for example, the influence of a set of parameters. * Keep a organized back up of the Project giving the possibility of easily reproduce it. .. note:: To run a Batch Analysis a **Command File** need to be previously written. This chapter explains how to write such a file. The Batch analysis can be started by cliking in the ``New Batch`` button as per :numref:`batch_buttom_fig`. .. _batch_buttom_fig: .. figure:: fig/batch_buttom.png :align: center :figclass: align-center :width: 400pt :class: screenshot :alt: Batch Access Buttom Batch Access Buttom After clicking on ``New Batch`` button as per :numref:`batch_buttom_fig`, the files need to be uploaded in the "Batch Analysis Form" as per :numref:`batch_form_fig`. .. _batch_form_fig: .. figure:: fig/batch_form.png :align: center :figclass: align-center :width: 400pt :class: screenshot :alt: Batch analysis form Batch Analysis Form Parameters are (numbers refer to :numref:`batch_form_fig`): 1. ``Models``: Selection of the Models (Excel spreadsheet) referred by the Batch Command File. 2. ``Command File``: File describing all conditions (Node, Regular analysis, Sensitivity analysis, Combination Analysis, etc) to be considered in the Batch analysis. Preparing the `Command File` ------------------------------ By the button `Project Management` two templates of `Command File` are available, as per :numref:`batch_temp_access`: * **Batch Template**: this template contains comments and general instructions to write a `Command File`. The use of this template is recommended for those starting with the `Batch tool`. * **Minified Batch Template**: this template omits comments and instructions to write a `Command File`. The use of this template is recommended for those feeling comfortable with the `Batch Tool`. .. _batch_temp_access: .. figure:: fig/batch_temp_access.png :width: 500pt :align: center :alt: Batch Template Access :figclass: align-center :class: screenshot Batch File - template access As shown by the templates, three main sections may be considered in the `Command File` (numbers refer to :numref:`Mini_Batch_temp_sections`): 1. ``[regular analysis]``: where the default parameters and Models are defined. 2. ``[combination analysis]``: where combination analysis between Models may be defined. This section can be deleted in case no combination analysis is required. 3. ``[sensitivity analysis]``: where sensitivity analysis between Models may be defined. This section can be deleted in case no sensitivity analysis is required. .. _Mini_Batch_temp_sections: .. figure:: fig/Mini_Batch_temp_sections.png :width: 500pt :align: center :alt: Minified Batch Template - Main Sections :figclass: align-center :class: screenshot Command File - Minified Template Numbers refer to :numref:`Mini_Batch_temp_sections`: 1. ``[regular analysis]`` section The `[regular analysis]` subsection is divided in *[__default__] subsection* and models *[regular analysis example 1, 2, 3, etc] subsection*. - ``[[__default__]]`` subsection This subsection defines the main parameters for the analysis and default parameters for the regular nodes. It needs to be filled with the project's default parameters as described in :ref:`params_model_parameters`. The [[__default__]] parameters are: `Model and Configuration` * :ref:`params_units` * :ref:`params_doors_position` * :ref:`params_load_cases_to_run` * :ref:`params_sub-modelling_zone` `Runtime` * :ref:`params_engine` * :ref:`params_timestep` * :ref:`params_sampling` * :ref:`params_write_data_on_event` * :ref:`params_timeout` * :ref:`params_convergence_criteria` * :ref:`params_post-convergence_margin` `Runtime Advanced` * :ref:`params_adaptive_strategy` * :ref:`params_adaptive_strategy_max_co_target` * :ref:`params_adaptive_strategy_neighborhood_zone` * :ref:`params_adaptive_strategy_max_co_ramp` * :ref:`params_default_opening_latency` * :ref:`params_raw_merging` . - ``[[regular analysis example 1, 2, 3, etc]]`` subsection In the ``[[regular analysis example 1, 2, 3, etc]]`` subsections (see :numref:`Mini_Batch_temp_sections` as reference), the Nodes need to be defined. The parameters defined for each Node are: * ``input``: the input is the model (excell file tittle). * ``node_id``: Node identification. * ``comments``: to add any relevant comment. .. note:: all parameters defined in the subsection ``[__default__]`` can be overlapped by new parameters for a specific Node if they are written inside the Node definition ``[regular analysis example 1, 2 3, etc]``. 2. ``[combination analysys] section`` In this subsection (see :numref:`Mini_Batch_temp_sections` as reference), any kind of combination between the Nodes defined in the other subsections, can be requested. * ``node_id``: defines the identification of the combination node_id. * ``nodes``: defines the nodes that will be combined. * ``comments``: to add any relevant comments 3. ``[sensitivity analysys]`` section In this subsection (see :numref:`Mini_Batch_temp_sections` as reference), any kind of sensitivity between the Nodes defined in the other subsections, can be requested. * ``node_id``: defines the identification of the combination node_id. * ``nodes``: defines the nodes that will be combined. * ``comments``: to add any relevant comments .. seealso:: More details about `batch analysis` may be found in :ref:`tuto5`. Tweaks Facility ==================== The `Tweaks facilities` allows the user to `modify` (tweak) pre-defined parameters as: `volume`, `cp`, `vent area`, etc. It is acessible via excell sheet called `Tweaks`. The `Tweaks` excell sheet is available in the `Advanced Template`, see :numref:`analysis_tweaks` and :numref:`tweaks_sheet` .. _analysis_tweaks: .. figure:: fig/analysis_tweaks.png :width: 500pt :align: center :alt: Advanced Template - Download :figclass: align-center :class: screenshot Advanced Template - Download The :numref:`tweaks_sheet` shows the `Tweaks excell sheet` to ben considered. .. _tweaks_sheet: .. figure:: fig/tweaks_sheet.png :width: 400pt :align: center :alt: Tweaks sheet :figclass: align-center :class: screenshot Tweaks Excell Sheet The numbers below refer to :numref:`tweaks_sheet`) 1. ``id`` : this column identifies the `tweaked parameter(s)`. 2. ``lcid``: this column identifies the `load case id` that will be considered for the `tweaked parameter(s)`. 3. ``tab``: this column identifies the reference `tab` that the `tweaked parameter(s)` will be considered. 4. ``tweaked_id``: this column identifies inside the `tab` selected, the corresponding id of the tweaked parameter(s). 5. ``parameter``: this column identifies inside the `tab` selected, the corresponding column of the tweaked parameter(s). 6. ``value``: to add the value that should be considered by the `Tweaks facility`. .. seealso:: More details about `tweaks facility` may be found in :ref:`tuto6`. .. _adaptive_runtime_parameters: Adaptive Runtime parameters =========================== Courant number --------------- As for ESonix3, ESonix is able to adapt the time step during run time. This means that the ESonix controller will increase time step when the model does not change quickly, and will decrease time step when the model is evolving quickly. The actual value that ESonix is tracking is the volume's :term:`courant number`. For each volume *i*, this positive number is the absolute mass flow balance divided by the volume's mass: .. math:: {Co}_i = \frac{\left | \Sigma \dot{m}_{ij}\right | }{m_i} \geqslant 0 With big mass flow balance (*e.g.* the volume is loosing a lot of hair compaired to its volume), the *courant number* will increase rapidly, and the simulation's controller can decrease the time step to capture the event in a smooth way. .. _courant_neighborhood_zone: Volume neighborhood zone (neighborhood) ---------------------------------------- When defining an adaptive time step, it is important to specify the *checked zone*, or *checked neighborhood*. This zone defines where the Courant numbers will be checked. The Maximum Courant number is the maximum of *all* or *part* of the model's volumes Co. At a given instant, the volume having the biggest *Co* is the volume that is changing in a fastest way. We can therefore assume that connections attached to this volume are the one where the pressure differential :math:`\Delta_p` is becoming critical. The Controller will adapt the time step as follows: .. math:: \Delta T_{i+1} = B \cdot \Delta T_i \frac{Co_{target}}{Co_{max}} where: * :math:`B`: dumping coefficient * :math:`\Delta T_{i}`: time step at instant *i* * :math:`\Delta T_{i+1}`: time step at instant *i+1* * :math:`Co_{target}`: Max courant number target * :math:`Co_{max}`: Max courant number observed within the checked :term:`volume neighborhood zone`.