.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/api/plot_scenario.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_examples_api_plot_scenario.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_api_plot_scenario.py:


Scenario
========

.. GENERATED FROM PYTHON SOURCE LINES 25-38

.. code-block:: default

    from gemseo.api import configure_logger
    from gemseo.api import create_design_space
    from gemseo.api import create_discipline
    from gemseo.api import create_scenario
    from gemseo.api import get_available_scenario_types
    from gemseo.api import get_scenario_differentiation_modes
    from gemseo.api import get_scenario_inputs_schema
    from gemseo.api import get_scenario_options_schema
    from gemseo.api import monitor_scenario

    configure_logger()






.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <RootLogger root (INFO)>



.. GENERATED FROM PYTHON SOURCE LINES 39-53

In this example, we will discover the different functions of the API to
related to scenarios, which are the |g|' objects
dedicated to the resolution of a problem, e.g. optimization or trade-off,
associated with a list of disciplines and a design space. All classes
implementing scenarios inherit from :class:`.Scenario` which is an
abstract class. Classical concrete classes are :class:`.MDOScenario` and
:class:`.DOEScenario`, respectively dedicated to optimization and trade-off
problems.

Get available scenario type
---------------------------
The API function :meth:`~gemseo.api.get_available_scenario_types` can be used
to get the available scenario types (:class:`.MDOScenario` and
:class:`.DOEScenario`).

.. GENERATED FROM PYTHON SOURCE LINES 53-55

.. code-block:: default

    print(get_available_scenario_types())





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    ['MDO', 'DOE']




.. GENERATED FROM PYTHON SOURCE LINES 56-60

Get scenario options schema
---------------------------
The :meth:`~gemseo.api.get_scenario_options_schema` function can be used
to get the options of a given scenario type:

.. GENERATED FROM PYTHON SOURCE LINES 60-62

.. code-block:: default

    print(get_scenario_options_schema("MDO"))





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    {'$schema': 'http://json-schema.org/draft-04/schema', 'type': 'object', 'properties': {'linearization_mode': {'description': 'Linearization mode', 'enum': ['auto', 'direct', 'reverse', 'adjoint'], 'type': 'string'}, 'jac_approx_type': {'description': 'Jacobian approximation type', 'enum': ['finite_differences', 'complex_step'], 'type': 'string'}, 'jax_approx_step': {'minimum': 0, 'exclusiveMinimum': True, 'description': 'Step for finite differences or complex step for Jacobian approximation', 'type': 'number'}, 'jac_approx_use_threading': {'description': 'if True, use Threads instead of processes\n to parallelize the execution. \nMultiprocessing will serialize all the disciplines, \nwhile multithreading will share all the memory.\n This is important to note if you want to execute the same\n  discipline multiple times, you shall use multiprocessing', 'type': 'boolean'}, 'jac_approx_wait_time': {'description': 'Time waited between two forks of the process or thread when using parallel jacobian approximations (parallel=True)', 'minimum': 0, 'type': 'number'}, 'jac_approx_n_processes': {'minimum': 1, 'description': 'maximum number of processors or threads on \nwhich the jacobian approximation is performed\n by default, 1 means no parallel calculations', 'type': 'integer'}, 'cache_type': {'description': 'Type of cache to be used.  \nBy default, simple cache stores the last execution inputs and outputs  \nin memory only to avoid computation of the outputs if the inputs are identical.\n To store more executions, use HDF5 caches, which stores data on the disk.\n There is a hashing mechanism which avoids reading on the disk for every calculation.', 'type': 'string'}, 'cache_tolerance': {'minimum': 0, 'description': 'Numerical tolerance on the relative norm of input vectors \n to consider that two sets of inputs are equal, and that the outputs may therefore be returned from the cache without calculations.', 'type': 'number'}, 'cache_hdf_file': {'format': 'uri', 'description': 'Path to the HDF5 file to store the cache data.', 'type': 'string'}, 'cache_hdf_node_name': {'description': 'Name of the HDF dataset to store the discipline\n data. If None, the discipline name is used.', 'type': 'string'}, 'name': {'description': 'The name to be given to this scenario. If None, use the name of the class.', 'type': 'null'}, 'grammar_type': {'description': 'The type of grammar to use for IO declaration , e.g. JSON_GRAMMAR_TYPE or SIMPLE_GRAMMAR_TYPE.', 'type': 'string'}}, 'required': ['grammar_type']}




.. GENERATED FROM PYTHON SOURCE LINES 63-87

Create a scenario
-----------------
The API function :meth:`~gemseo.api.create_scenario` can be used
to create a scenario:

- The four first arguments are mandatory:

  - :code:`disciplines`: the list of :class:`.MDODiscipline`
    (or possibly, a single :class:`.MDODiscipline`),
  - :code:`formulation`: the formulation name,
  - :code:`objective_name`: the name of the objective function
    (one of the discipline outputs)
  - :code:`design_space`: the :class:`.DesignSpace` or
    the file path of the design space

- The other arguments are optional:

  - :code:`name`: scenario name,
  - :code:`scenario_type`: type of scenario,
    either `"MDO"` (default) or `"DOE"` ,
  - :code:`**options`: options passed to the formulation.

- This function returns an instance of :class:`.MDOScenario` or
  :class:`.DOEScenario`.

.. GENERATED FROM PYTHON SOURCE LINES 87-101

.. code-block:: default


    discipline = create_discipline("AnalyticDiscipline", expressions={"y": "x1+x2"})
    design_space = create_design_space()
    design_space.add_variable("x1", 1, "float", 0.0, 1.0)
    design_space.add_variable("x2", 1, "float", 0.0, 1.0)

    scenario = create_scenario(
        discipline, "DisciplinaryOpt", "y", design_space, scenario_type="DOE"
    )
    scenario.execute({"algo": "fullfact", "n_samples": 25})
    scenario.post_process(
        "ScatterPlotMatrix", variable_names=["x1", "x2", "y"], save=False, show=True
    )





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

        INFO - 10:07:04:  
        INFO - 10:07:04: *** Start DOEScenario execution ***
        INFO - 10:07:04: DOEScenario
        INFO - 10:07:04:    Disciplines: AnalyticDiscipline
        INFO - 10:07:04:    MDO formulation: DisciplinaryOpt
        INFO - 10:07:04: Optimization problem:
        INFO - 10:07:04:    minimize y(x1, x2)
        INFO - 10:07:04:    with respect to x1, x2
        INFO - 10:07:04:    over the design space:
        INFO - 10:07:04:    +------+-------------+-------+-------------+-------+
        INFO - 10:07:04:    | name | lower_bound | value | upper_bound | type  |
        INFO - 10:07:04:    +------+-------------+-------+-------------+-------+
        INFO - 10:07:04:    | x1   |      0      |  None |      1      | float |
        INFO - 10:07:04:    | x2   |      0      |  None |      1      | float |
        INFO - 10:07:04:    +------+-------------+-------+-------------+-------+
        INFO - 10:07:04: Solving optimization problem with algorithm fullfact:
        INFO - 10:07:04: Full factorial design required. Number of samples along each direction for a design vector of size 2 with 25 samples: 5
        INFO - 10:07:04: Final number of samples for DOE = 25 vs 25 requested
        INFO - 10:07:04: ...   0%|          | 0/25 [00:00<?, ?it]
        INFO - 10:07:05: ... 100%|██████████| 25/25 [00:00<00:00, 2186.99 it/sec, obj=2]
        INFO - 10:07:05: Optimization result:
        INFO - 10:07:05:    Optimizer info:
        INFO - 10:07:05:       Status: None
        INFO - 10:07:05:       Message: None
        INFO - 10:07:05:       Number of calls to the objective function by the optimizer: 25
        INFO - 10:07:05:    Solution:
        INFO - 10:07:05:       Objective: 0.0
        INFO - 10:07:05:       Design space:
        INFO - 10:07:05:       +------+-------------+-------+-------------+-------+
        INFO - 10:07:05:       | name | lower_bound | value | upper_bound | type  |
        INFO - 10:07:05:       +------+-------------+-------+-------------+-------+
        INFO - 10:07:05:       | x1   |      0      |   0   |      1      | float |
        INFO - 10:07:05:       | x2   |      0      |   0   |      1      | float |
        INFO - 10:07:05:       +------+-------------+-------+-------------+-------+
        INFO - 10:07:05: *** End DOEScenario execution (time: 0:00:00.019905) ***

    <gemseo.post.scatter_mat.ScatterPlotMatrix object at 0x7fdbfa5a1f40>



.. GENERATED FROM PYTHON SOURCE LINES 102-104

- The :meth:`~gemseo.api.get_scenario_inputs_schema` function can be used
  to get the inputs of a scenario:

.. GENERATED FROM PYTHON SOURCE LINES 104-106

.. code-block:: default

    print(get_scenario_inputs_schema(scenario))





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    {'$schema': 'http://json-schema.org/draft-04/schema', 'algo': {'type': 'string', 'enum': ['CustomDOE', 'DiagonalDOE', 'OT_SOBOL', 'OT_RANDOM', 'OT_HASELGROVE', 'OT_REVERSE_HALTON', 'OT_HALTON', 'OT_FAURE', 'OT_MONTE_CARLO', 'OT_FACTORIAL', 'OT_COMPOSITE', 'OT_AXIAL', 'OT_OPT_LHS', 'OT_LHS', 'OT_LHSC', 'OT_FULLFACT', 'OT_SOBOL_INDICES', 'fullfact', 'ff2n', 'pbdesign', 'bbdesign', 'ccdesign', 'lhs']}, 'type': 'object', 'properties': {'eval_jac': {'type': 'boolean'}, 'algo': {'type': 'string'}, 'algo_options': {'type': 'object'}, 'n_samples': {'minimum': 1, 'type': 'integer'}}, 'required': ['algo']}




.. GENERATED FROM PYTHON SOURCE LINES 107-111

Get scenario differentiation modes
----------------------------------
The :meth:`~gemseo.api.get_scenario_differentiation_modes` can be used to
get the available differentiation modes of a scenario:

.. GENERATED FROM PYTHON SOURCE LINES 111-113

.. code-block:: default

    print(get_scenario_differentiation_modes())





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    ['user', 'complex_step', 'finite_differences', 'no_derivatives']




.. GENERATED FROM PYTHON SOURCE LINES 114-126

Monitor a scenario
------------------
To monitor a scenario execution programmatically,
ie get a notification when a discipline status is changed,
use :meth:`~gemseo.api.monitor_scenario`.
The first argument is the scenario to monitor, and the second is an
observer object, that is notified by its update(atom) method, which takes an
:class:`~gemseo.core.execution_sequence.AtomicExecSequence` as argument.
This method will be called every time a discipline status changes.
The atom represents a discipline's position in the process. One discipline
can have multiple atoms, since one discipline can be used in multiple
positions in the MDO formulation.

.. GENERATED FROM PYTHON SOURCE LINES 126-144

.. code-block:: default



    class Observer:
        """Observer."""

        def update(self, atom):
            """Update method.

            :param AtomicExecSequence atom: atomic execution sequence.
            """
            print(atom)


    scenario = create_scenario(
        discipline, "DisciplinaryOpt", "y", design_space, scenario_type="DOE"
    )
    monitor_scenario(scenario, Observer())
    scenario.execute({"algo": "fullfact", "n_samples": 25})




.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    DOEScenario(RUNNING)
        INFO - 10:07:05:  
        INFO - 10:07:05: *** Start DOEScenario execution ***
        INFO - 10:07:05: DOEScenario
        INFO - 10:07:05:    Disciplines: AnalyticDiscipline
        INFO - 10:07:05:    MDO formulation: DisciplinaryOpt
        INFO - 10:07:05: Optimization problem:
        INFO - 10:07:05:    minimize y(x1, x2)
        INFO - 10:07:05:    with respect to x1, x2
        INFO - 10:07:05:    over the design space:
        INFO - 10:07:05:    +------+-------------+-------+-------------+-------+
        INFO - 10:07:05:    | name | lower_bound | value | upper_bound | type  |
        INFO - 10:07:05:    +------+-------------+-------+-------------+-------+
        INFO - 10:07:05:    | x1   |      0      |   0   |      1      | float |
        INFO - 10:07:05:    | x2   |      0      |   0   |      1      | float |
        INFO - 10:07:05:    +------+-------------+-------+-------------+-------+
        INFO - 10:07:05: Solving optimization problem with algorithm fullfact:
        INFO - 10:07:05: Full factorial design required. Number of samples along each direction for a design vector of size 2 with 25 samples: 5
        INFO - 10:07:05: Final number of samples for DOE = 25 vs 25 requested
        INFO - 10:07:05: ...   0%|          | 0/25 [00:00<?, ?it]
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
    AnalyticDiscipline(RUNNING)
    AnalyticDiscipline(PENDING)
        INFO - 10:07:05: ... 100%|██████████| 25/25 [00:00<00:00, 1887.93 it/sec, obj=2]
        INFO - 10:07:05: Optimization result:
        INFO - 10:07:05:    Optimizer info:
        INFO - 10:07:05:       Status: None
        INFO - 10:07:05:       Message: None
        INFO - 10:07:05:       Number of calls to the objective function by the optimizer: 25
        INFO - 10:07:05:    Solution:
        INFO - 10:07:05:       Objective: 0.0
        INFO - 10:07:05:       Design space:
        INFO - 10:07:05:       +------+-------------+-------+-------------+-------+
        INFO - 10:07:05:       | name | lower_bound | value | upper_bound | type  |
        INFO - 10:07:05:       +------+-------------+-------+-------------+-------+
        INFO - 10:07:05:       | x1   |      0      |   0   |      1      | float |
        INFO - 10:07:05:       | x2   |      0      |   0   |      1      | float |
        INFO - 10:07:05:       +------+-------------+-------+-------------+-------+
        INFO - 10:07:05: *** End DOEScenario execution (time: 0:00:00.025950) ***
    AnalyticDiscipline(DONE)
    DOEScenario(DONE)

    {'eval_jac': False, 'algo': 'fullfact', 'n_samples': 25}




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.523 seconds)


.. _sphx_glr_download_examples_api_plot_scenario.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: plot_scenario.py <plot_scenario.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: plot_scenario.ipynb <plot_scenario.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_