.. _userguide-case_stages:

***************
Case and stages
***************


Case
====

When a study is created, an empty **case** is automatically added. The *case*
represents a particular *Aster* study case within the application.

Content of the case is filled in by means of various editing operations. In
addition to the **Current Case** which always represents a case being edited
by the user, there can be other types of cases:

* **Run cases**: these are cases which contain results of *Code_Aster*
  calculations,
* **Backup cases**: backup copies of the *Current Case*.

For more details about features related to the cases, refer to the
:ref:`userguide-case_management` chapter.


Stages
======

A case is composed of **stages** representing the different phases of the
*Aster* calculation.


Graphical mode and text mode of the stages
------------------------------------------

The stages can be managed either in *graphical* or in *text* mode.

The **graphical** mode is used to manage the stages by filling them via
input panels in the application's interface.

The **text** mode lets the user entering *Aster* commands. This mode can be
used, for instance, to apply features of *Code_Aster*.


.. |stage_graphical| image:: /images/stage_graphical.png
.. |stage_text| image:: /images/stage_text.png

The stages in *graphical* mode are represented in the *Data Settings* tab by the
|stage_graphical| icon, and those in *text* mode by the |stage_text| icon.

.. important::
    *By default* the stages are created in *graphical* mode.

It is possible to change the mode of a stage via the context menu or
*Operations* menu.

.. warning::
    A warning message is displayed if the application cannot convert
    a stage from *text* mode to *graphical* mode.


Add stage
---------

To add a stage, perform any of below listed actions:

* Click on the *Add stage* icon of the toolbar,
* Use *Operations > Add Stage* menu,
* Use *Add Stage* context menu on the case in the *Data Settings* tab,
* Use the keyboard shortcut *Ctrl+Shift+N*.

It is possible to rename the stage by selecting it in the *Data Settings* tab
and then using the *Rename* context menu, or by pressing the keyboard
shortcut *F2*.


Import stage
------------

It is possible to import an *Aster* command file as a case stage.

For this you can either:

* Click the *Add stage from file* icon of the toolbar,
* Use the *Operations > Add Stage from File* menu,
* Use *Add Stage from File* context menu on the case in the *Data Settings* tab,
* Use the keyboard shortcut *Ctrl+Shift+I*.

.. important::
    The application parses the command file and creates a stage in the
    *graphical* mode from the contents of the file. If the file contains commands
    that cannot be interpreted by the application, the stage will be created in
    *text* mode with the contents of the file.

Also, it is possible to import *Aster* command file as a stage in *text* mode,
i.e. without its automatic conversion to the *graphical* mode. This can be done
by:

* Using the *Operations > Add Text Stage from File* menu,
* Using *Add Text Stage from File* context menu on the case in the
  *Data Settings* tab.


Import stage from template
--------------------------

It is possible to create a stage by importing *Aster* command file from the
predefined template. The template command files can be created by the user in
the ``~/.config/salome/asterstudy_templates`` directory. These files appear as
items in:

* *Operations > Add Stage from Template* and *Operations > Add Text Stage from Template*
  main menus,
* *Add Stage from Template* and *Add Text Stage from Template* sub-menus in
  the case's context menu in *Data Settings* tab.


Export stage
------------

Similarly, it is possible to export a stage to an *Aster* command file:

* Click the *Export command file* icon of the toolbar,
* Use the *Operation > Export Command File* menu,
* Use the *Export Command File* context menu on the stage in the *Data Settings*
  tab,
* Use the keyboard shortcut *Ctrl+Shift+E*.

If the stage is in *graphical* mode, the command file is generated from the
commands defined in the stage; if the stage is in *text* mode, the content of
the stage is directly exported to the file.


Rename stage
------------

Stages are added to a study with the default name.
To rename a stage, select it in the *Data Settings* tab and then:

* Use *Edit > Rename* main menu,
* Use *Rename* context menu item,
* Press *F2* key.


Delete stage
------------

A stage can be removed from the case by using the corresponding toolbar
button, menu, or keyboard shortcut (*Del*).

.. warning::
    Deleting of a stage will automatically remove all stages which follow it.


Search
======

It is possible to search the study tree. To do this, select the *Data Settings*
tab and press *Ctrl+F*, use *Find* context menu or *Edit > Find* main menu.

The search box appears at the bottom of the study tree.

It is possible to search on the following criteria:

* *Command*: search by Aster command names.
    * Example: if the user types `DEF`, items created by commands like
      `DEFI_MATERIAU` are highlighted.
* *Concept*: search by the names of existing concepts.
    * Example: if the user types `MAT`, the item corresponding to the command
      `MATE = AFFE_MATERIAU (...)` is highlighted.
* *Keyword*: search by the keywords of the commands.
    * Example: `COMMAND (GROUP_MA=ALPHA)` is highlighted, if user types
      `GROUP`.
* *Group*: search on the names of groups of mesh nodes or elements.
    * Example: `COMMAND (GROUP_MA=BETA)` is highlighted, if the user types
      `BET`.

.. important::
    In *Concept* mode, the search tool finds concepts recursively, i.e. if one
    concept refers to another one which name suits the search criterion, this
    first concept is also included into the search result.

    * Example: if the user types `MESH`, the item corresponding to the command
      `MODEL = AFFE_MODELE(MAILLAGE=MESH)` is also highlihted, in addition to
      the `MESH` item itself.

The nodes of the study corresponding to the search criterion entered by the user
are then highlighted in yellow background, and it is possible to navigate
between them by clicking *<* (previous result) and *>* (next result) buttons
or pressing *F3*, *Shift+F3* shortcuts.

The search is case insensitive and is performed on the words **containing**
the value entered by the user.

.. figure:: /images/search.png
   :alt: Search in the study tree
   :align: center

   **Search in the study tree**
