diff --git a/docs/source/intro/breaking_changes.rst b/docs/source/intro/breaking_changes.rst deleted file mode 100644 index ff1fd20561..0000000000 --- a/docs/source/intro/breaking_changes.rst +++ /dev/null @@ -1,258 +0,0 @@ -:orphan: - -.. _updating_backward_incompatible_changes: - -***************************** -Backward Incompatible Changes -***************************** - -Updating from 0.12.* to 1.* -============================ - -Updating from 0.12.* to 1.* - -Besides the generic update instructions, the following applies: - - * Finish all running legacy workflows. - The legacy workflows are completely deprecated and all data will be removed from your database, so make sure to create a backup (see point 5). - * The upgrade involves several long-running migrations. Migrating databases containing millions of nodes can take a few hours. - -Breaking changes from 0.12.* to 1.* -=================================== - -The following list covers the most important backward incompatible changes between ``aiida-core==0.12.*`` and ``aiida-core==1.0.0``. - -General -------- - -- Reorganization of some second-level modules. Various classes and functions have been moved, renamed or replaced. See :ref:`this page ` for the rules on the publicness of parts of the python API `[#2357] `__ -- The module ``aiida.work`` has been renamed to ``aiida.engine`` and reorganized significantly `[#2524] `__ -- The module ``aiida.scheduler`` has been renamed to ``aiida.schedulers`` `[#2498] `__ -- The module ``aiida.transport`` has been renamed to ``aiida.transports`` `[#2498] `__ -- The module ``aiida.utils`` has been removed and its contents have been placed in other places where appropriate `[#2357] `__ -- Requirements were moved from ``setup_requirements.py`` to ``setup.json`` `[#2307] `__ - - -ORM ---- - -In order to define a clearer interface for users to the AiiDA entities, and allow (in the future) to swap between different profiles, the underlying hierarchy of nodes and links has been reworked (and a new paradigm has been implemented, with a "frontend" class that all users will interact with, and a "backend" class that users should never use directly, that implements the interaction to the database with a common interface, independent of the underlying ORM). -The reorganisation of nodes and linktypes is mostly invisible to the user, but existing import statements will need to be updated. - -- Refactoring the ORM `[#2190] `__\ `[#2210] `__\ `[#2227] `__\ `[#2225] `__\ `[#2481] `__\ `[#2544] `__ -- Renamed the node classes for the various process types -- ``WorkCalculation`` to ``WorkChainNode`` `[#2192] `__ -- ``FunctionCalculation`` to ``WorkFunctionNode`` `[#2189] `__ -- ``JobCalculation`` to ``CalcJobNode`` `[#2184] `__ `[#2201] `__ -- ``InlineCalculation`` to ``CalcFunctionNode`` `[#2195] `__ -- Reorganization of the ``aiida.orm`` module, all node sub classes are now located under ``aiida.orm.nodes`` `[#2402] `__\ `[#2497] `__ -- Make ``Code`` a real sub class of ``Data`` `[#2193] `__ -- Implement new link types `[#2220] `__ - - - ``CREATE``: ``CalculationNode -> Data`` - - ``RETURN``: ``WorkflowNode -> Data`` - - ``INPUT_CALC``: ``Data -> CalculationNode`` - - ``INPUT_WORK``: ``Data -> WorkflowNode`` - - ``CALL_CALC``: ``WorkflowNode -> CalculationNode`` - - ``CALL_WORK``: ``WorkflowNode -> WorkflowNode`` - -- Moved the plugin factories to ``aiida.plugins.factories`` `[#2498] `__ -- Methods that operated on the repository of a ``Node`` instance have been moved to a ``Repository`` utility that is exposed through the ``Node.repository`` property `[#2506] `__ -- Removed the ``Error`` data sub class and its entry point `[#2529] `__ -- Removed the ``FrozenDict`` data sub class and its entry point `[#2532] `__ -- Renamed the ``ParameterData`` data sub class to ``Dict`` `[#2517] `__ - - -``QueryBuilder`` ----------------- - -- Changed relationship indicator keywords, e.g. ``input_of`` is now ``with_outgoing``. `[#2224] `__\ `[#2278] `__ -- Changed type of UUIDs returned by the ``QueryBuilder`` to always be of type unicode `[#2259] `__ - - -``Group`` ---------- - -- Change group type strings `[#2329] `__ - - - ``data.upf.family`` to ``data.upf`` - - ``aiida.import`` to ``auto.import`` - - ``autogroup.run`` to ``auto.run`` - - custom ones to ``user`` - -- Remove ``Group.query`` and ``Group.group_query`` methods have been removed `[#2329] `__ -- Renamed ``type`` column of ``Group`` database model to ``type_string`` `[#2329] `__ -- Renamed ``name`` column of ``Group`` database model to ``label`` `[#2329] `__ -- Class method ``Group.get_or_create`` has been removed, use the collection method ``Group.objects.get_or_create`` instead -- Class method ``Group.get_from_string`` has been removed, use the class method ``Group.get`` instead - - -``Node`` --------- - -- The column ``type`` has been renamed to ``node_type`` `[#2522] `__ -- The methods ``get_inputs``, ``get_outputs``, ``get_inputs_dict`` and ``get_outputs_dict`` have been removed and replace by ``get_incoming`` and ``get_outgoing`` `[#2236] `__ -- Removed the link manager methods ``Node.inp`` and ``Node.out`` and the functionality has partially been replaced by: `[#2569] `__ - - - The link manager properties ``inputs`` and ``outputs`` for the ``CalculationNode`` and ``WorkflowNode`` classes. - - Added the ``Data.creator`` property - - Added the ``ProcessNode.caller`` property - - Functionality to traverse the graph with tab completion when there is no uniqueness on the label is no longer supported and ``get_incoming`` and ``get_outgoing`` should be used instead. - -- The classes ``Node``, ``ProcessNode`` can no longer be stored but only their sub classes `[#2301] `__ - - -``Data`` --------- - -- ``Kind.is_alloy()`` has been changed to a property ``Kind.is_alloy`` `[#2374] `__ -- ``Kind.has_vacancies()`` has been changed to a property ``Kind.has_vacancies`` `[#2374] `__ -- ``StructureData.is_alloy()`` has been changed to a property ``StructureData.is_alloy`` `[#2374] `__ -- ``StructureData.has_vacancies()`` has been changed to a property ``StructureData.has_vacancies`` `[#2374] `__ -- ``CifData._get_aiida_structure()`` has been renamed to ``CifData.get_structure()``. `[#2422] `__ -- ``CifData`` default library used in ``get_structure`` to convert to ``StructureData`` has been changed from ``ase`` to ``pymatgen`` `[#1257] `__ -- ``SinglefileData`` the methods ``get_file_content``, ``add_path`` and ``remove_path`` have been removed in favor of ``put_object_from_file`` and ``get_content`` `[#2506] `__ -- ``ArrayData.iterarrays()`` has been renamed to ``ArrayData.get_iterarrays()``. `[#2422] `__ -- ``TrajectoryData._get_cif()`` has been renamed to ``TrajectoryData.get_cif()``. `[#2422] `__ -- ``TrajectoryData._get_aiida_structure()`` has been renamed to ``TrajectoryData.get_structure()``. `[#2422] `__ -- ``StructureData._get_cif()`` has been renamed to ``StructureData.get_cif()``. `[#2422] `__ -- ``Code.full_text_info()`` has been renamed to ``Code.get_full_text_info()``. `[#2422] `__ -- ``Code.is_hidden()`` has been renamed and changed to ``Code.hidden`` property. `[#2422] `__ -- ``RemoteData.is_empty()`` has been changed to a property ``RemoteData.is_empty``. `[#2422] `__ -- The arguments ``stepids`` and ``cells`` of the ``TrajectoryData.set_trajectory()`` method are made optional which has implications on the ordering of the arguments passed to this method. `[#2422] `__ -- The list of atomic symbols for ``TrajectoryData`` is no longer stored as array data but is now accessible through the ``TrajectoryData.symbols`` attribute. `[#2422] `__ -- Removed deprecated methods ``BandsData._prepare_dat_1`` and ``BandsData._prepare_dat_2`` `[#3114] `__ -- Removed deprecated method `KpoinstData.bravais_lattice` `[#3114] `__ -- Removed deprecated method `KpoinstData._set_bravais_lattice` `[#3114] `__ -- Removed deprecated method `KpoinstData._get_or_create_bravais_lattice` `[#3114] `__ -- Removed deprecated method `KpoinstData.set_kpoints_path` `[#3114] `__ -- Removed deprecated method `KpoinstData._find_bravais_info` `[#3114] `__ -- Removed deprecated method `KpoinstData.find_bravais_lattice` `[#3114] `__ -- Removed deprecated method `KpoinstData.get_special_kpoints` `[#3114] `__ - -``Process`` ------------ - -- Metadata inputs that used to start with an underscore (``_label``, ``_description`` and ``_options``) no longer use an underscore and have moved within the ``metadata`` namespace `[#1105] `__ -- Non-storable input ports are now markable as such through the ``non_db`` keyword `[#1105] `__ - - -Inline calculations -------------------- - -- The ``make_inline`` and ``optional_inline`` decorators have been replaced by ``calcfunction``. `[#2203] `__ - - -``JobCalculation`` ------------------- - -In the new engine, it is not possible to launch calculation jobs by first creating an instance of the Calculation and then calling the ``calculation.use_xxx`` methods, as it was common in early versions of AiiDA. -Instead, you need to pass the correct Calculation class to the ``run`` or ``submit`` function, passing the nodes to link as input as ``kwargs``. -For the past few versions, we have kept back-compatibility by supporting both ways of submitting. In version 1.0 we have decided to keep only one single way of submitting calculations for simplicity. - -- ``JobCalculation`` has been replaced by ``CalcJob`` process class `[#2389] `__ -- Custom methods on the node class should now be implemented through a ``CalculationTools`` plugin `[#2331] `__ -- Explicit ``set_`` methods of the ``JobCalculation`` have been replaced with generic ``set_option`` method `[#2361] `__ -- Explicit ``get_`` methods of the ``JobCalculation`` have been replaced with generic ``get_option`` method `[#1961] `__ -- New calculation job states have been introduced set as an attribute, only to be used for querying `[#2389] `__ -- The ``DbCalcState`` table that recorded the old job state of ``JobCalculations`` has been removed `[#2389] `__ - - -``Parser`` ----------- - -- ``parse_from_retrieved`` has been renamed to ``parse``. In addition the arguments and return signatures have changed, for details see the PR `[#2397] `__ - - -``WorkChain`` -------------- - -- The free function ``submit`` in any ``WorkChain`` should be replaced with ``self.submit``. -- The future returned by ``submit`` no longer has the ``pid`` attribute but rather ``pk``. -- The ``workfunction`` decorator can only be used for functions that return one of the inputs they receive, for all other use the ``calcfunction`` -- The ``get_inputs_template class`` method has been replaced by ``get_builder``. See the `section on the process builder in the documentation `__ on how to use it. -- The ``input_group`` has been deprecated and been replaced by namespaces. See the `section on ports in the documentation `__ on how to use them. -- The use of a ``.`` (period) in output keys is not supported in ``Process.out`` because that is now reserved to indicate namespaces. - - -Legacy workflows ----------------- - -- Remove implementation of legacy workflows `[#2379] `__ - - -``verdi`` ---------- - -The ``verdi`` command line interface has been migrated over to a new system (called ``click``), making the interface of all ``verdi`` commands consistent: now the way to specify a node (via a PK, a UUID or a LABEL) is the same for all commands, and command-line options that have the same meaning use the same flags in all commands. -To make this possible, the interface of various verdi commands has been changed to ensure consistency. -Also the output of most commands has been homogenised (e.g. to print errors or warnings always in the same style). -Moreover, some of the commands have been renamed to be consistent with the new names of the classes in AiiDA. - -- Removed ``verdi data plugins`` in favor of ``verdi plugin list`` `[#3114] `__ -- Removed ``verdi code rename`` in favor of ``verdi code relabel`` `[#3114] `__ -- Removed ``verdi code update`` in favor of ``verdi code duplicate`` `[#3114] `__ -- Removed ``verdi work`` in favor of ``verdi process`` `[#2574] `__ -- Removed ``verdi calculation`` in favor of ``verdi process`` and ``verdi calcjob`` `[#2574] `__ -- Removed ``verdi workflows`` `[#2379] `__ -- Deprecated the commands to set and get config options ``verdi devel *property*`` in favor of ``verdi config`` `[#2354] `__ -- ``verdi code show`` no longer shows number of calculations by default to improve performance, with ``--verbose`` flag to restore old behavior `[#1428] `__ -- The tab-completion activation for ``verdi`` has changed, simply replace the ``eval "$(verdi completioncommand)"`` line in your activation script with ``eval "$(_VERDI_COMPLETE-source verdi)"`` - - -Daemon ------- - -- Each profile now has its own daemon that can be run completely independently in parallel, so ``verdi daemon configureuser`` has been removed `[#1217] `__ -- Replaced ``Celery`` with ``Circus`` as the daemonizer of the daemon `[#1213] `__ - - -Schedulers ----------- - -- Renamed ``aiida.daemon.execmanager.job_states`` to ``JOB_STATES``, conforming to python conventions `[#1799] `__ -- Abstract method ``aiida.scheduler.Scheduler._get_detailed_jobinfo_command()`` raises ``aiida.common.exceptions.FeatureNotAvailable`` (was ``NotImplemented``). -- Moved the ``SchedulerFactory`` to ``aiida.plugins.factories`` `[#2498] `__ - - -Transports ----------- - -- Moved the ``TransportFactory`` to ``aiida.plugins.factories`` `[#2498] `__ - - -Export import -------------- - -- New export archive format introduced ``v0.6``. Older archives will automatically be converted when using ``verdi import``, or alternatively can be manually exported using ``verdi export migrate`` - - -.. _update_older_versions: - -Older versions -============== - -To determine the current version of your installation use ``verdi --version``. -If the command does not exist, you have an older version of AiiDA, in which case you need to get it from the ``aiida.__init__.py`` file. -Update instructions for older versions can be found in the documentation of the corresponding version: - -* `0.11.*`_ -* `0.10.*`_ -* `0.9.*`_ -* `0.8.* Django`_ -* `0.7.* Django`_ -* `0.6.* Django`_ -* `0.6.* SqlAlchemy`_ -* `0.5.* Django`_ -* `0.4.* Django`_ - - -.. _0.11.*: https://aiida-core.readthedocs.io/en/v0.12.2/installation/updating.html#updating-from-0-11-to-0-12-0 -.. _0.10.*: http://aiida-core.readthedocs.io/en/v0.10.0/installation/updating.html#updating-from-0-9-to-0-10-0 -.. _0.9.*: http://aiida-core.readthedocs.io/en/v0.10.0/installation/updating.html#updating-from-0-9-to-0-10-0 -.. _0.8.* Django: http://aiida-core.readthedocs.io/en/v0.9.1/installation/index.html#updating-from-0-8-django-to-0-9-0-django -.. _0.7.* Django: http://aiida-core.readthedocs.io/en/v0.8.1/installation/index.html#updating-from-0-7-0-django-to-0-8-0-django -.. _0.6.* Django: http://aiida-core.readthedocs.io/en/v0.7.0/installation.html#updating-from-0-6-0-django-to-0-7-0-django -.. _0.6.* SqlAlchemy: http://aiida-core.readthedocs.io/en/v0.7.0/installation.html#updating-from-0-6-0-django-to-0-7-0-sqlalchemy -.. _0.5.* Django: http://aiida-core.readthedocs.io/en/v0.7.0/installation.html#updating-from-0-5-0-to-0-6-0 -.. _0.4.* Django: http://aiida-core.readthedocs.io/en/v0.5.0/installation.html#updating-from-0-4-1-to-0-5-0 diff --git a/docs/source/intro/configuration.rst b/docs/source/intro/configuration.rst index 3f7fbfcbcc..b4ff3e3740 100644 --- a/docs/source/intro/configuration.rst +++ b/docs/source/intro/configuration.rst @@ -1,51 +1,13 @@ -.. _configure_aiida: +.. _intro:configure: ================= Configuring AiiDA ================= -.. _tab-completion: -Verdi tab-completion --------------------- -The ``verdi`` command line interface has many commands and options, which can be tab-completed to simplify your life. -Enable tab-completion with the following shell command: -.. code-block:: bash - - eval "$(_VERDI_COMPLETE=source verdi)" - -Place this command in your startup file, i.e. one of - -* the startup file of your shell (``.bashrc``, ``.zsh``, ...), if aiida is installed system-wide, -* the `activate script `_ of your virtual environment, or -* a `startup file `_ for your conda environment. - -In order to enable tab completion in your current shell, make sure to source the start-up file once. - -.. note:: - - This line replaces the ``eval "$(verdi completioncommand)"`` line that was used in ``aiida-core<1.0.0``. While this continues to work, support for the old line may be dropped in the future. - -.. _setup_aiida: - -AiiDA profile setup -------------------- - -After successful installation, you need to create an AiiDA profile via AiiDA's command line interface ``verdi``. - -Most users should use the interactive quicksetup: - -.. code-block:: console - - $ verdi quicksetup - -which leads through the installation process and takes care of creating the corresponding AiiDA database. - -For maximum control and customizability, one can use ``verdi setup`` and set up the database manually as explained below. - -.. _database: +.. _intro:setup:database: Database setup -------------- @@ -222,42 +184,6 @@ If you open a new terminal for example, be sure to activate it first with: $ source ~/.virtualenvs/aiida/bin/activate -.. _start_daemon: - -Start the daemon ----------------- - -The AiiDA daemon process runs in the background and takes care of processing your submitted calculations and workflows, checking their status, retrieving their results once they are finished and storing them in the AiiDA database. - -The AiiDA daemon is controlled using three simple commands: - - * ``verdi daemon start``: start the daemon - * ``verdi daemon status``: check the status of the daemon - * ``verdi daemon stop``: stop the daemon - -.. note:: - - While operational, the daemon logs its activity to a file in ``~/.aiida/daemon/log/`` (or, more generally, ``$AIIDA_PATH/.aiida/daemon/log``). - Get the latest log messages via ``verdi daemon logshow``. - - -Final checks ------------- - -Use the ``verdi status`` command to check that all services are up and running: - -.. code-block:: console - - $ verdi status - - ✓ profile: On profile quicksetup - ✓ repository: /repo/aiida_dev/quicksetu - ✓ postgres: Connected to aiida@localhost:5432 - ✓ rabbitmq: Connected to amqp://127.0.0.1?heartbeat=600 - ✓ daemon: Daemon is running as PID 2809 since 2019-03-15 16:27:52 - -In the example output, all service have a green check mark and so should be running as expected. - Using AiiDA in Jupyter ---------------------- diff --git a/docs/source/intro/get_started.rst b/docs/source/intro/get_started.rst index 4caaf47486..01be0c2a63 100644 --- a/docs/source/intro/get_started.rst +++ b/docs/source/intro/get_started.rst @@ -1,4 +1,4 @@ -.. _intro/get_started: +.. _intro:get_started: **************** Getting Started @@ -25,8 +25,8 @@ These are outlined below, followed by a recommended "quick-install" route on you +++ - :link-badge:`install/software,Software install,ref,badge-primary text-white` - :link-badge:`install/aiida-core,aiida-core install,ref,badge-primary text-white` + :link-badge:`intro:install:software,Software install,ref,badge-primary text-white` + :link-badge:`intro:install:aiida-core,aiida-core install,ref,badge-primary text-white` --------------- @@ -39,7 +39,7 @@ These are outlined below, followed by a recommended "quick-install" route on you +++ - :link-badge:`install/virtual_environments,Environments Tutorial,ref,badge-primary text-white` + :link-badge:`intro:install:virtual_environments,Environments Tutorial,ref,badge-primary text-white` :link-badge:`https://anaconda.org/conda-forge/aiida-core,aiida-core on Conda,url,badge-primary text-white` --------------- @@ -53,7 +53,7 @@ These are outlined below, followed by a recommended "quick-install" route on you +++ - :link-badge:`install/docker,Docker Tutorial,ref,badge-primary text-white` + :link-badge:`intro:install:docker,Docker Tutorial,ref,badge-primary text-white` :link-badge:`https://hub.docker.com/r/aiidateam/aiida-core,aiida-core on DockerHub,url,badge-primary text-white` --------------- @@ -70,6 +70,7 @@ These are outlined below, followed by a recommended "quick-install" route on you :link-badge:`https://materialscloud.org/quantum-mobile,Quantum Mobile,url,badge-primary text-white` :link-badge:`https://aiidalab.materialscloud.org,AiiDA lab,url,badge-primary text-white` +.. _intro:quick_install: Quick Installation ================== @@ -101,7 +102,7 @@ Here we first provide a simple approach for installation on your local computer. ``aiida-core`` can be installed from `PyPi `__. You will then need to install |PostgreSQL| and |RabbitMQ| depending on your operating system. - :link-badge:`install/software,Get install instructions,ref,badge-primary text-white` + :link-badge:`intro:install:software,Get install instructions,ref,badge-primary text-white` Before working with AiiDA, you must first initialize a database storage area on disk. @@ -148,6 +149,9 @@ At this point you now have a working AiiDA environment, from which you can add a $ eval "$(_VERDI_COMPLETE=source verdi)" + :link-badge:`how-to:installation:configure:tab-completion,Read More,ref,badge-primary text-white` + + In order to run computations, some additional steps are required to start the services that manage these background processes. The |RabbitMQ| service is started, to manage communication between processes and remember process states, even when you shut down your computer: diff --git a/docs/source/intro/installation.rst b/docs/source/intro/installation.rst index 434b13adfb..9f66788716 100644 --- a/docs/source/intro/installation.rst +++ b/docs/source/intro/installation.rst @@ -1,13 +1,13 @@ -.. _intro/installation: +.. _intro:install: ********************* Detailed Installation ********************* -.. _install/software: +.. _intro:install:prerequisites: -Software Packages -================= +Installing Prerequisites +======================== AiiDA is designed to run on `Unix `_ operating systems and requires the following software: @@ -56,7 +56,7 @@ Below, we provide installation instructions for a number of operating systems. git python3-dev python3-pip $ pip install aiida-core - See :ref:`Ubuntu instructions` for details. + See :ref:`Ubuntu instructions` for details. .. dropdown:: MacOS X (Homebrew) @@ -69,7 +69,7 @@ Below, we provide installation instructions for a number of operating systems. $ python get-pip.py $ pip install aiida-core - See :ref:`MacOS X (Homebrew) instructions` for details. + See :ref:`MacOS X (Homebrew) instructions` for details. .. dropdown:: MacOS X (MacPorts) @@ -81,7 +81,7 @@ Below, we provide installation instructions for a number of operating systems. $ python get-pip.py $ pip install aiida-core - See :ref:`MacOS X (MacPorts) instructions` for details. + See :ref:`MacOS X (MacPorts) instructions` for details. .. dropdown:: Gentoo Linux @@ -93,7 +93,7 @@ Below, we provide installation instructions for a number of operating systems. $ emerge --ask dev-python/pip $ pip install aiida-core - See :ref:`Gentoo Linux instructions` for details. + See :ref:`Gentoo Linux instructions` for details. .. dropdown:: Windows Subsystem for Linux @@ -106,12 +106,12 @@ Below, we provide installation instructions for a number of operating systems. # install rabbitmq on windows $ pip install aiida-core - See :ref:`WSL instructions` for details. + See :ref:`WSL instructions` for details. -.. _install/details_ubuntu: +.. _intro:install:prerequisites:ubuntu: Ubuntu -====== +------ To install the prerequisites on Ubuntu and any other Debian derived distribution, you can use the ``apt`` package manager. The following will install the basic ``python`` requirements and the ``git`` source control manager: @@ -153,10 +153,10 @@ Finally install the aiida-core python environment: - For a more detailed description of database requirements and usage see the :ref:`database section`. - For problems with installing RabbitMQ, refer to the detailed instructions provided on the `RabbitMQ website for Debian based distributions `_. -.. _install/details_brew: +.. _intro:install:prerequisites:brew: Mac OS X (homebrew) -=================== +------------------- For Mac OS we recommend using the `Homebrew`_ package manager. If you have not installed Homebrew yet, you can do so with the following command: @@ -201,10 +201,10 @@ Finally install the aiida-core python environment: - For problems with installing RabbitMQ, refer to the detailed instructions provided on the `RabbitMQ website for Homebrew based distributions `_. - For details on the installation of the ``pip`` package manager, refer to `their documentation `_ -.. _install/details_macports: +.. _intro:install:prerequisites:macports: Mac OS X (MacPorts) -=================== +------------------- .. _macports: https://www.macports.org/ @@ -255,10 +255,10 @@ Finally install the aiida-core python environment: - For a more detailed description of database requirements and usage see the :ref:`database section`. - For details on the installation of the ``pip`` package manager, refer to `their documentation `_ -.. _install/details_gentoo: +.. _intro:install:prerequisites:gentoo: Gentoo Linux -============ +------------ To install RabbitMQ on a Gentoo distribution through the ``portage`` package manager run the following command: @@ -297,10 +297,10 @@ Make sure that RabbitMQ is running with: If you still have trouble getting RabbitMQ to run, please refer to the detailed instructions provided on the `website of RabbitMQ itself for generic Unix systems `_. -.. _install/details_wsl: +.. _intro:install:prerequisites:wsl: Windows Subsystem for Linux (Ubuntu) -==================================== +------------------------------------ The guide for Ubuntu above can generally be followed, but there are a few things to note: @@ -359,10 +359,10 @@ It may be worth considering adding some of these commands to your ``~/.bashrc`` For using WSL as a developer, please see the considerations made in our `wiki-page for developers `_. -.. _install/virtual_environments: +.. _intro:install:virtual_environments: -Virtual environments -==================== +Using virtual environments +========================== AiiDA depends on a number of third party python packages, and usually on specific versions of those packages. In order not to interfere with third party packages needed by other software on your system, we **strongly** recommend isolating AiiDA in a virtual python environment. @@ -409,80 +409,11 @@ If you have `Conda`_ installed then you can directly create a new environment wi $ conda activate $ conda deactivate aiida -.. _directory_location: -Isolating AiiDA environments ----------------------------- +.. _intro:install:aiida-core: -By default, the AiiDA configuration is stored in the directory ``~/.aiida``. -When running AiiDA in multiple virtual environments (using ``venv`` or ``conda``), -you can ask AiiDA to use a separate ``.aiida`` configuration directory per environment. - -1. Create your virtual environment ``aiida2`` -2. Edit the activation script ``/path/to/new/virtual/environment/aiida2/bin/activate`` - and append a line to set the ``AIIDA_PATH`` environment variable: - - .. code-block:: bash - - export AIIDA_PATH='/path/to/new/virtual/environment/aiida2/' # use .aiida configuration in this folder - eval "$(_VERDI_COMPLETE=source verdi)" # e.g. set up tab completion - -.. note:: - For ``conda``, create a directory structure ``etc/conda/activate.d`` in - the root folder of your conda environment (e.g. - ``/home/user/miniconda/envs/aiida``), and place a file ``aiida-init.sh`` in - that folder which exports the ``AIIDA_PATH``. - -3. Deactivate and re-activate the virtual environment - -You can test that everything is set up correctly if you can reproduce the following: - -.. code-block:: console - - (aiida2)$ echo $AIIDA_PATH - /path/to/new/virtual/environment/aiida2/ - (aiida2)$ verdi profile list - Info: configuration folder: /home/my_username/.virtualenvs/aiida/.aiida2 - Critical: configuration file /home/my_username/.virtualenvs/aiida/.aiida2/config.json does not exist - -Now simply :ref:`create a new AiiDA profile ` in the ``aiida2`` environment. - -``AIIDA_PATH`` Details -...................... - -The value of ``AIIDA_PATH`` can be a colon-separated list of paths. -AiiDA will go through each of the paths and check whether they contain a ``.aiida`` directory. -The first configuration directory that is encountered will be used. -If no ``.aiida`` directory is found, one will be created in the last path that was considered. - -For example, the directory structure in your home folder ``~/`` might look like this:: - - . - ├── .aiida - └── project_a -    ├── .aiida -    └── subfolder - - -If you leave the ``AIIDA_PATH`` variable unset, the default location ``~/.aiida`` will be used. -However, if you set : - -.. code-block:: console - - $ export AIIDA_PATH='~/project_a:' - -the configuration directory ``~/project_a/.aiida`` will be used. - -.. warning:: - - If there was no ``.aiida`` directory in ``~/project_a``, AiiDA would have created it for you. - Thus make sure to set the ``AIIDA_PATH`` correctly. - - -.. _install/aiida-core: - -aiida-core package -================== +Installing the aiida-core package +================================= .. _Conda: https://anaconda.org/conda-forge/aiida-core .. _PyPI: https://pypi.python.org/pypi/aiida-core @@ -510,8 +441,6 @@ Alternatively, you can create a directory where to clone the AiiDA source code a $ git clone https://github.com/aiidateam/aiida-core $ pip install -e aiida-core -.. _install_optional_dependencies: - There are additional optional packages that you may want to install, which are grouped in the following categories: * ``atomic_tools``: packages that allow importing and manipulating crystal structure from various formats @@ -544,45 +473,89 @@ After installing AiiDA packages, always remember to update the reentry cache usi $ reentry scan -.. _updating_aiida: +.. _intro:setup: + +Setting up the installation +=========================== + +.. _intro:setup:profile: + +AiiDA profile setup +------------------- + +After successful installation, you need to create an AiiDA profile via AiiDA's command line interface ``verdi``. + +Most users should use the interactive quicksetup: + +.. code-block:: console + + $ verdi quicksetup + +which leads through the installation process and takes care of creating the corresponding AiiDA database. + +For maximum control and customizability, one can use ``verdi setup`` and set up the database manually as explained below. + +.. admonition:: Want to manage multiple profiles? + :class: title-icon-read-more -Updating aiida-core -=================== + See the :ref:`managing profiles how-to `. -1. Enter the python environment where AiiDA is installed -2. Finish all running calculations. - After migrating your database, you will not be able to resume unfinished calculations! - Data of finished calculations will of course be automatically migrated. -3. Stop the daemon using ``verdi daemon stop`` -4. :ref:`Create a backup of your database and repository` -.. warning:: +.. _intro:setup:start_daemon: - Once you have migrated your database, you can no longer go back to an older version of ``aiida-core`` (unless you restore your database and repository from a backup). +Starting the daemon +------------------- -5. Update your ``aiida-core`` installation +The AiiDA daemon process runs in the background and takes care of processing your submitted calculations and workflows, checking their status, retrieving their results once they are finished and storing them in the AiiDA database. - - If you have installed AiiDA through ``pip`` simply run: ``pip install --upgrade aiida-core`` - - If you have installed from the git repository using ``pip install -e .``, first delete all the ``.pyc`` files (``find . -name "*.pyc" -delete``) before updating your branch. +The AiiDA daemon is controlled using three simple commands: + + * ``verdi daemon start``: start the daemon + * ``verdi daemon status``: check the status of the daemon + * ``verdi daemon stop``: stop the daemon + +.. note:: + + While operational, the daemon logs its activity to a file in ``~/.aiida/daemon/log/`` (or, more generally, ``$AIIDA_PATH/.aiida/daemon/log``). + Get the latest log messages via ``verdi daemon logshow``. + +.. _intro:setup:final_checks: + +Final checks +------------ + +Use the ``verdi status`` command to check that all services are up and running: + +.. code-block:: console + + $ verdi status + + ✓ profile: On profile quicksetup + ✓ repository: /repo/aiida_dev/quicksetup + ✓ postgres: Connected to aiida@localhost:5432 + ✓ rabbitmq: Connected to amqp://127.0.0.1?heartbeat=600 + ✓ daemon: Daemon is running as PID 2809 since 2019-03-15 16:27:52 -6. Migrate your database with ``verdi -p database migrate``. - Depending on the size of your database and the number of migrations to perform, data migration can take time, so please be patient. +In the example output, all service have a green check mark and so should be running as expected. -After the database migration finishes, you will be able to continue working with your existing data. +.. admonition:: Want to know more about managing your install? + :class: tip title-icon-read-more -.. admonition:: Updating from version 0.12? - :class: warning title-icon-important + See the :ref:`Installation how-to ` - If your update involved a change in the major version number of ``aiida-core``, expect :ref:`backwards incompatible changes` and check whether you also need to update your installed plugin packages. + :link-badge:`how-to:installation:configure,Configuring,ref,badge-primary text-white` + :link-badge:`how-to:installation:update,Updating,ref,badge-primary text-white` + :link-badge:`how-to:installation:backup:software,Backing-up,ref,badge-primary text-white` -.. _install/docker: +.. _intro:install:docker: -Docker -====== +Using the Docker image +====================== -AiiDA maintains a `Docker `__ image on `Docker Hub `__, which is particularly useful for learning and testing purposes. -It is a great way to quickly get started on the tutorials. +AiiDA maintains a `Docker `__ image on `Docker Hub `__. +This image contains a pre-configured AiiDA environment, and so is particularly useful for learning and testing purposes. +It is a great way to quickly get started on the tutorials! Follow Docker's `install guide `__ to download Docker and start its daemon. Now you can pull the aiida-core image straight from Docker Hub, for a specific version.