.. _siconos_getting_started:

Quickstart
==========

This manual aims at giving you a short overview of the software functionnalities and to provide some guidelines for your first steps with nonsmooth systems
simulation with Siconos. There you will learn basics things to know to describe a nonsmooth problem or to run a simulation using siconos, for both APIs, C++ or Python.
For a more detailed description of Siconos and its functionnalities please check the :ref:`full_documentation` table of content.


What is Siconos?
----------------

Siconos is an open-source scientific software primarily targeted at modeling and simulating nonsmooth dynamical systems :cite:`Acary.Brogliato2008`: 

* **Mechanical systems** (rigid or solid) with unilateral contact and Coulomb friction and impact
  (Nonsmooth mechanics, contact dynamics, multibody systems dynamics or granular materials).
* **Switched Electrical Circuits** such as electrical circuits with ideal and piecewise linear components: power converter, rectifier, Phase-Locked Loop (PLL) or Analog-to-Digital converter.
* Sliding mode control systems.
* Biology Gene regulatory networks.

Other applications are found in Systems and Control (hybrid systems, differential inclusions,
optimal control with state constraints), Optimization (Complementarity systems and Variational inequalities), 
Fluid Mechanics, Computer Graphics, ...

Check :ref:`siconos_examples` manual for an overview of the various problems handled with Siconos.
  

Try it
------

You can use one of the end-user docker images available in `siconos-tutorials registry <https://gricad-gitlab.univ-grenoble-alpes.fr/nonsmooth/siconos-tutorials/container_registry>`_ .

For example, start a jupyter container including siconos, all running examples and some tutorials notebooks,

.. code-block:: bash


   docker run -p 8888:8888 -ti gricad-registry.univ-grenoble-alpes.fr/nonsmooth/siconos-tutorials/siconoslab-main

   # Then, access in your browser at http://localhost:8888/...
   # The exact address will be printed on your screen as a result of the command above.


Another possible (but unstable) way to start with Siconos, try the tutorial notebooks available here in the directory siconos-notebooks

.. image:: https://plmbinder.math.cnrs.fr/binder/badge_logo.svg
   :target: https://plmbinder.math.cnrs.fr/binder/v2/git/https%3A%2F%2Fgricad-gitlab.univ-grenoble-alpes.fr%2Fnonsmooth%2Fsiconos-tutorials.git/HEAD

This page proposes a Python interactive interface (notebooks) to Siconos, that you can use through your web browser, online.


Siconos usage in a few steps
----------------------------

#.  :ref:`download` software
#.  :ref:`siconos_install_guide`
#.  Write and run your first simulation.

There are two ways to use Siconos

* As a library (C++) : in that case you need to write a c++ file (driver) to describe and solve your problem,
  and then run siconos to build and execute your program.
* As a Python package.

Python API is generated (pybind11) from C++ and thus both API are quite equivalent although C++ might be more complete. 
 
Anyway, for new users we recommend the Python API which is easier to understand.

Below are two examples (Python and C++) of a Siconos process. We just build and print a first-order dynamical
system (See :cpp:class:`siconos::modeling::siconos::modeling::FirstOrderLinearDS`).

.. admonition:: tip

   have a look to the numerous `examples in siconos-tutorials repository <https://gricad-gitlab.univ-grenoble-alpes.fr/nonsmooth/siconos-tutorials/>`_ to inspire you and use the search bar to find details on all (Python, C or C++) objects)

**Example of Siconos Python API usage**

.. code-block:: python

   # File run.py
   # import siconos package
   import siconos.modeling as sm
   # import numpy package
   import numpy as np

   # Create a dynamical system
   size = 10
   x0 = np.random.random(size)
   ds = sk.FirstOrderLinearDS(x0)
   print(ds)

And:

.. code-block:: bash

   siconos run.py
   # --> will call python and anything else required

.. admonition:: tip

   More on *siconos* script options, try:

   .. code-block:: shell

      siconos --help
      siconos --info

**Example of Siconos C++ API usage**

Write a c++ file, e.g. run.cpp

.. code-block:: c++
   
   // File run.cpp
   #include "SiconosKernel.hpp"
   int main()
   {
    unsigned int size = 10;
    auto x0 = std::make_shared<siconos::algebra::SiconosVector>(size);
    auto A = std::make_shared<(siconos::algebra::SiconosDenseMatrix>(size, size);
    A->randomize();

    auto ds = std::make_shared<siconos::modeling::FirstOrderLinearDS(x0, A);
    ds->display();
   }

And, compile, link and execute (in one shot, thanks to siconos script)::

.. code-block:: shell

   siconos run.cpp    

For new simulation, start with the :ref:`template for c++ driver file <template_siconos_driver>`
or try to mimic one of the examples available at https://gricad-gitlab.univ-grenoble-alpes.fr/nonsmooth/siconos-tutorials.git.
  

More
----

* :doc:`users_guide/index`
* :doc:`reference/index``
* :doc:`tutorial_python/index`
* :doc:`tutorial_cpp/siconos_tutorial`
* :ref:`running_siconos`