Getting started
===============

With pyDRAMA, the 5 base DRAMA tools (OSCAR, MIDAS, ARES, SARA and CROC) can be controlled by defining their inputs
through a python dictionary, which would otherwise be set in the DRAMA GUI.
To make sure everything is set up correctly, you can run the following basic test script:

.. code-block:: python

   from drama import oscar

   if __name__ == "__main__":
      results = oscar.run(semiMajorAxis=6500)

      print(results)

All tools expose a very similar set of functions, that allow to load configurations from either the default project,
or an existing DRAMA 3 project. These can be modified and passed to the :code:`run()` function, which executes the tool
with the provided set of inputs, and returns a dictionary with the results (or errors if the execution was unsuccessful).

Below is a generic example, highlighting the different available functionalities:

.. code-block:: python

   # Import oscar, same for midas, ares, etc.
   from drama import oscar

   # We can get the default project config for oscar
   default_config = oscar.get_basic_config()

   # Or the config of an existing DRAMA 3 project (directory or .dpz)
   # Currently, this option doesn't work with DRAMA 4 projects
   my_project_config = oscar.get_basic_config(project="path/to/my_project")
   my_dpz_project_config = oscar.get_basic_config(project="path/to/project.dpz")

   # The resulting dicts can be edited
   my_project_config['dragCoefficient'] = 1.6

   # Now we can run one (or all) of our configs:
   oscar_results = oscar.run([default_config, my_project, my_project_config])

   # If there are errors in the execution, they go into oscar_results['errors']
   for err in oscar_results['errors']:
      print(err)
   # The results of successful runs go into oscar_results['results']
   # This will be list, with one entry per successful run, containing a dict with results data
   for res in oscar_results['results']:
      print(res)
   # See the documentation of the respective module for more information on the results and inputs

More examples can be found on the :doc:`Examples <./examples>` page.