.. _ModifyAnalysis-label:

==============================
How to modify default analysis
==============================
This how-to guide explains the process to modify default analysis object in DIANA by making use of
:py:func:`~viiapackage.viiaAnalysis.viia_modify_analysis` function in the **mainscript**.

This modification function is available for A10, A12, A13 and A15 analysis only. The modification
that can be done using this function is also limited but it covers majority of the commonly
encountered use case.

-----------------------------
Modifying A10 or A13 analysis
-----------------------------
Normally, an nonlinear static analysis is created as follows:

.. code-block:: python

   project.viia_create_datfile()
   project.viia_analysis(analysis_nr='A10', run=False)

To make use of the modification functionality, the analysis has to be created slightly different, in two steps
(same can be applied for A13):

Step 1 - Create analysis but suppress creation of files
=======================================================
Use the following command to create the analysis, notice that by setting 'suppress_analysis' argument to True, we are
actually suppressing creation of files in analysis sub-folder.

.. code-block:: python

   analysis = project.viia_analysis(analysis_nr='A10', run=False, suppress_analysis=True)

Step 2 - Modifying analysis and creating files in analysis sub-folder
=====================================================================
Use the returned analysis object to modify analysis in DIANA. We set the 'analysis' keyword argument to the object we
created at the end of step 1.

.. code-block:: python

   project.viia_modify_analysis(analysis=analysis, mod_param=[[...]])

The argument 'mod_param' (see the expression above) should contain the items for modification. More explanation is
given below for how to create input for argument 'mod_param'. Please note that analysis files will be created by deafult
in this step.

In A10 analysis, by default the step size inside the last execute block is set to 0.5 0.5 i.e. 2 steps of 0.5 each.
A start step size of 0.5 0.5 is expressed as a list, [0.5, 2]. Let's say the goal is to give input in 'mod_param' that
modifies this to 0.1(10) i.e. 10 steps of size 0.1 each. The following command will set start step to 0.1(10):

.. code-block:: python
   
   project.viia_modify_analysis(analysis=analysis,
       mod_param=[['Structural nonlinear 3', 'Execute block D', 'Start steps', [0.1, 10]]])

When run in DIANA, this will set the start steps to 0.1(10) as visible in the image below.

.. figure:: _static/howto_modify_analysis/001.png
   :align:   center

   Input for 'mod_param' values that are needed to change start steps in 'Execute block D'.

It is also possible to modify multiple items in one statement. By providing multiple inputs inside the main list in
argument 'mod_param' you can modify multiple settings.

The following example modifies the maximum number of iterations in 'Execute Block E' of 'Structural nonlinear 3' to
100. It also changes the force convergence tolerance for the execute block. And the third, fourth and fifth input will
remove 'OUTPUT_1A_MAX', 'OUTPUT_5A', 'OUTPUT_GEO1' from output items. The last one will change start steps to 0.1(10)
instead of 0.5(2).

.. code-block:: python

   project.viia_modify_analysis(analysis=analysis_mod, mod_param=[
       ['Structural nonlinear 3', 'Execute block E', 'Equilibrium iteration', 'Maximum number of iterations', 100],
       ['Structural nonlinear 2', 'Execute block E', 'Equilibrium iteration', 'force', True, 'convergence tolerance',
           0.1],
       ['OUTPUT', 'OUTPUT_1A_MAX'],
       ['OUTPUT', 'OUTPUT_5A'],
       ['OUTPUT', 'OUTPUT_GEO1'],
       ['Structural nonlinear 3', 'Execute block D', 'start steps', project.create_start_steps(
           initial_stress=None, use_load_previous_phase=True, add_load_combination=None, steps=[[0.1, 10]])]])

-----------------------------
Modifying A12 or A15 analysis
-----------------------------
Normally an A12 analysis is created as follows:

.. code-block:: python

   project.viia_create_loads('Base motion')
   project.viia_add_basemotion_signals(signal_list=[1, 2, 3, 4, 5, 6, 8])
   project.viia_create_load_combination_base_motion('S1')
   project.viia_analysis(analysis_nr='A12', run=False, signals=['S1'])

To make use of the modification functionality, the analysis has to be created slightly different, in two steps
(same can be applied for A15):

Step 1 - Create analysis- A12 but suppress creation of files
============================================================
Use the following command to create A12 analysis, notice that by setting 'suppress_analysis' argument to True, we are
actually suppressing creation of files in analysis sub-folder.

.. code-block:: python

   project.viia_create_loads('Base motion')
   project.viia_add_basemotion_signals(signal_list=[1, 2, 3, 4, 5, 6, 8])
   project.viia_create_load_combination_base_motion('S1')
   analysis = project.viia_analysis(analysis_nr='A12', run=False, signals=['S1'], suppress_analysis=True)

Step 2 - Modifying A12 analysis and creating files in analysis sub-folder
=========================================================================
Use the returned analysis object to modify analysis in DIANA. We set the 'analysis' keyword argument to the object we
created at the end of step 1 (analysis_mod).

.. code-block:: python

   project.viia_modify_analysis(analysis=analysis_mod, mod_param=[[...]])

The argument 'mod_param' (see the expression above) should contain the items for modification. More explanation is
given below for how to create input for argument 'mod_param'. Please note that in this step, analysis files
will be created by default.

In the example below, we will create A12 analysis and modify multiple items in a single step. The mod_param output that
is shown below does the following. Here we change maximum number of iterations in 'Execute Block E' of 'Structural
nonlinear 3' to 100.

.. code-block:: python

   project.viia_modify_analysis(
       analysis=analysis, mod_param=[
           ['Structural nonlinear 3', 'Execute block E', 'Equilibrium iteration', 'Maximum number of iterations', 100]])

--------
Examples
--------
This section will give some examples of how to define the argument 'mod_param' properly when using
viia_modify_analysis().

Example 1 - Deleting unnecessary output items
=============================================
Let's say we want to delete some output items from either A10 or A12 analysis.

.. figure:: _static/howto_modify_analysis/002.png
   :align:   center

   Output items selected for deletion.

.. code-block:: python

   project.viia_modify_analysis(
       analysis=analysis, mod_param=[
           ['OUTPUT', 'OUTPUT_GEO2'],
           ['OUTPUT', 'OUTPUT_GEO3'],
           ['OUTPUT', 'OUTPUT_GEO_REF'],
           ['OUTPUT', 'OUTPUT_MOVIE']])

.. figure:: _static/howto_modify_analysis/003.png
   :align:   center

   A12 analysis after selected output items has been deleted.

Please note that the same input for argument 'mod_param' can also be applied to A10 analysis to delete few of the
output items.

.. figure:: _static/howto_modify_analysis/004.png
   :align:   center

   A10 analysis after selected output items has been deleted.

Example 2 - User input for node number in an output block
=========================================================
Let's say we want to change the node numbers in some output blocks from either A10 or A12 analysis.

.. figure:: _static/howto_modify_analysis/005.png
   :align:   center

   Node numbers for output block 3 in A12 analysis - before user input.

.. code-block:: python

   project.viia_modify_analysis(
       analysis=analysis, mod_param=[
           ['Structural nonlinear 7', 'OUTPUT_3', 'user selection','nodes', [50,168,880,2253]]])

.. figure:: _static/howto_modify_analysis/006.png
   :align:   center

   Node number for output block 3 in A12 analysis - after user input.

Similar to the previous example, the modification of analysis can be applied to A10 as well, example of which
is shown below.

.. figure:: _static/howto_modify_analysis/007.png
   :align:   center

   Steps in the output block OUTPUT_STATIC-NL in A10 analysis - before user input.

.. code-block:: python

   project.viia_modify_analysis(
       analysis=analysis, mod_param=[
           ['Structural nonlinear 6', 'OUTPUT_STATIC-NL', 'steps',[2]]])

.. figure:: _static/howto_modify_analysis/008.png
   :align:   center

   Steps in the output block OUTPUT_STATIC-NL in A10 analysis - after user input.