diff options
Diffstat (limited to 'Docs/source')
| -rw-r--r-- | Docs/source/building/python.rst | 46 | ||||
| -rw-r--r-- | Docs/source/running_python/examples.rst | 21 | ||||
| -rw-r--r-- | Docs/source/running_python/how_to_run.rst | 48 | ||||
| -rw-r--r-- | Docs/source/running_python/running_picmi.rst | 35 | ||||
| -rw-r--r-- | Docs/source/running_python/running_python.rst | 1 |
5 files changed, 98 insertions, 53 deletions
diff --git a/Docs/source/building/python.rst b/Docs/source/building/python.rst index 106125ac7..56917dca5 100644 --- a/Docs/source/building/python.rst +++ b/Docs/source/building/python.rst @@ -1,7 +1,12 @@ Installing WarpX as a Python package ------------------------------------- +==================================== -WarpX' Python bindings depend on ``numpy``, ``mpi4py``, and ``picmistandard``. +A full Python installation of WarpX can be done, which includes a build of all of the C++ code, or a pure Python version can be made which only installs the Python scripts. + +For a full Python installation of WarpX +--------------------------------------- + +WarpX' Python bindings depend on ``numpy``, ``periodictable``, ``picmistandard``, and ``mpi4py``. Type @@ -15,13 +20,42 @@ or edit the ``GNUmakefile`` and set ``USE_PYTHON_MAIN=TRUE``, and type make -j 4 -This will compile the code, and install the Python bindings as a package (named ``pywarpx``) in your standard Python installation (i.e. in your ``site-packages`` directory). -The note on compiler options from the previous section also holds when compiling the Python package. +Additional compile time options can be specified as needed. +This will compile the code, and install the Python bindings and the Python scripts as a package (named ``pywarpx``) in your standard Python installation (i.e. in your ``site-packages`` directory). -In case you do not have write permissions to the default Python installation (e.g. typical on computer clusters), use the following command instead: +If you do not have write permission to the default Python installation (e.g. typical on computer clusters), add the ``--user`` install option to have WarpX installed elsewhere. .. code-block:: bash make -j 4 PYINSTALLOPTIONS=--user -In this case, you can also set the variable ``PYTHONUSERBASE`` to set the folder where ``pywarpx`` will be installed. +With ``--user``, the default location will be in your home directory, in ``~/.local``. +The location can be controlled by setting the environment variable ``PYTHONUSERBASE``. +In HPC environments, it is often recommended to install codes in scratch or work space which typically have faster disk access. + +The different dimensioned versions of WarpX, 3D, 2D, and RZ, can coexist in the Python installation. +The appropriate one will be imported depending on the input file. +Note, however, other options will overwrite - compiling with ``DEBUG=TRUE`` will replace the version compiled with ``DEBUG=FALSE`` for example. + + +For a pure Python installation +------------------------------ + +This avoids the compilation of the C++ and is recommended when only using the Python input files as preprocessors. +This installation depend on ``numpy``, ``periodictable``, and ``picmistandard``. + +Go into the ``Python`` subdirectory and run + +.. code-block:: bash + + python setup.py install + +This installs the Python scripts as a package (named ``pywarpx``) in your standard Python installation (i.e. in your ``site-packages`` directory). +If you do not have write permissions to the default Python installation (e.g. typical on computer clusters), add the ``--user`` install option to have WarpX installed elsewhere. + +.. code-block:: bash + + python setup.py install --user + +With ``--user``, the default location will be in your home directory, in ``~/.local``. +The location can be controlled by setting the environment variable ``PYTHONUSERBASE``. diff --git a/Docs/source/running_python/examples.rst b/Docs/source/running_python/examples.rst index 851d2e52f..4104bcf78 100644 --- a/Docs/source/running_python/examples.rst +++ b/Docs/source/running_python/examples.rst @@ -1,16 +1,27 @@ Example input files =================== -This section allows you to **download Python scripts** that correspond to different -physical situations. +WarpX includes several example Python input files corresponding to various physical situations. +These can be downloaded here (or obtained from the WarpX source). Beam-driven acceleration ------------------------ -* :download:`Without mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/plasma_acceleration_PICMI.py>` -* :download:`With mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/plasma_acceleration_PICMI.mr.py>` +* :download:`Without mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/PICMI_inputs_plasma_acceleration.py>` +* :download:`With mesh refinement<../../../Examples/Physics_applications/plasma_acceleration/PICMI_inputs_plasma_acceleration_mr.py>` Laser-driven acceleration ------------------------- -* :download:`Without mesh refinement<../../../Examples/Physics_applications/laser_acceleration/laser_acceleration_PICMI.py>` +* :download:`Without mesh refinement<../../../Examples/Physics_applications/laser_acceleration/PICMI_inputs_laser_acceleration.py>` + +Test cases +---------- + +There are also several test cases included that can be used for reference. + +* :download:`Gaussian beam<../../../Examples//Modules/gaussian_beam/PICMI_inputs_gaussian_beam.py>` +* :download:`Langmuir plasma wave test in 3d<../../../Examples//Tests/Langmuir/PICMI_inputs_langmuir_rt.py>` +* :download:`Langmuir plasma wave test in RZ<../../../Examples//Tests/Langmuir/PICMI_inputs_langmuir_rz_multimode_analyze.py>` +* :download:`Langmuir plasma wave test in 2D<../../../Examples//Tests/Langmuir/PICMI_inputs_langmuir2d.py>` + diff --git a/Docs/source/running_python/how_to_run.rst b/Docs/source/running_python/how_to_run.rst index 390abb8c2..870db91a3 100644 --- a/Docs/source/running_python/how_to_run.rst +++ b/Docs/source/running_python/how_to_run.rst @@ -1,8 +1,21 @@ -How to run a new simulation +Using WarpX with Python =========================== -After installing WarpX as a Python package, you can use its functionalities in a Python script -to run a simulation. +WarpX uses the PICMI standard for its Python input files. +See `PICMI information and source code <https://github.com/picmi-standard/picmi>`__. + +WarpX can be run in one of two modes. It can run as a preprocessor, using the +Python input file to generate an input file to be used by the C++ version, or +it can be run directly from Python. + +Example input files can be found in the section :doc:`examples`. +The examples support running in both modes by commenting and uncommenting the appropriate lines. + + +Using Python input as a preprocessor +------------------------------------ + +In this case, only the pure Python version needs to be installed, as described in :doc:`../building/python.rst`. In order to run a new simulation: @@ -10,9 +23,31 @@ In order to run a new simulation: * Add a **Python script** in the directory. -This file contains the numerical and physical parameters that define -the situation to be simulated. -Example input files can be found in the section :doc:`examples`. +The input file should have the line like "sim.write_input_file(file_name = 'inputs_from_PICMI')" +which runs the preprocessor, generating the C++ input file. + +* **Run** the script with Python: + +:: + + python <python_script> + +where ``<python_script>`` is the name of the script. +This creates the WarpX input file that you can run as normal with the WarpX executable. + + +Running WarpX directly from Python +---------------------------------- + +For this, a full Python installation of WarpX is required, as described in :doc:`../building/python.rst`. + +In order to run a new simulation: + +* Create a **new directory**, where the simulation will be run. + +* Add a **Python script** in the directory. + +The input file should have the line "sim.step()" which runs the simulation. * **Run** the script with Python: @@ -22,3 +57,4 @@ Example input files can be found in the section :doc:`examples`. where ``<n_ranks>`` is the number of MPI ranks used, and ``<python_script>`` is the name of the script. + diff --git a/Docs/source/running_python/running_picmi.rst b/Docs/source/running_python/running_picmi.rst deleted file mode 100644 index 509122f2e..000000000 --- a/Docs/source/running_python/running_picmi.rst +++ /dev/null @@ -1,35 +0,0 @@ -Running WarpX from PICMI -======================== - -See `PICMI information and source code <https://github.com/picmi-standard/picmi>`__. - -Generate WarpX input from PICMI python script ---------------------------------------------- - -You can **install** the PICMI standard via, for example: - -:: - - pip install picmistandard - -For other options, please visit link above. - -To install the WarpX implementation of PICMI go to the WarpX directory and do: - -:: - - cd Python - python setup.py install - -Then you can **run**, for example, the :download:`Example PICMI input script for laser-plasma acceleration <../../../Examples/Physics_applications/laser_acceleration/PICMI_inputs_laser_acceleration.py>` with - -:: - - python PICMI_inputs_laser_acceleration.py - -to create the WarpX input file that you can run with the WarpX executable. - -Running WarpX with python binding form PICMI --------------------------------------------- - -This option is not (yet) supported. diff --git a/Docs/source/running_python/running_python.rst b/Docs/source/running_python/running_python.rst index fc065cedc..cf960d431 100644 --- a/Docs/source/running_python/running_python.rst +++ b/Docs/source/running_python/running_python.rst @@ -6,4 +6,3 @@ Running WarpX from Python how_to_run examples - running_picmi |