diff --git a/source/conf.py b/source/conf.py index b622b9da7e481f7752033c65d1c57f8dbd7832f8..38eacd1afde746c634c3f1e0063e7fdb5b194e0c 100644 --- a/source/conf.py +++ b/source/conf.py @@ -33,7 +33,7 @@ intersphinx_disabled_domains = ["std"] templates_path = ["_templates"] -exclude_patterns = [] +exclude_patterns = ["guide.rst"] language = "pt_BR" diff --git a/source/guide.rst b/source/guide.rst index 52a33a3eaf4fee2f12c450bf856a1609176286a0..8661913ed65e72a257cce7c3c1342e011d149d05 100644 --- a/source/guide.rst +++ b/source/guide.rst @@ -1,14 +1,100 @@ +Hedears levels +============== -# with overline, for parts +The headers level and order are:: -* with overline, for chapters + # with overline, for parts + * with overline, for chapters + = for sections + - for subsections + ^ for subsubsections + " for paragraphs -= for sections -- for subsections +Contents tables +=============== +There are two type of the do contents tables, with `contens` and `toctree`. -^ for subsubsections +`toctree` +--------- +`toctree` are used to sumary between multiples files. -" for paragraphs +**Example:**:: + + .. toctree:: + :maxdepth: `<level>` + :caption: `<caption>` + :glob: +Where: + * `<level>`: level of max depth content table. + * `<caption>`: The caption of the content table, this parameter are optional. + * `<glob>`: Recursively + + +`contents` +---------- +`contents` are used to create *content table* only in the document. + +**Example:**:: + .. contents:: + :depth: `<level>` + :local: + +Where: + * `<level>`: level of max depth content table. + * `local`: set to show only index above the `.. contents`, if this parameter is omitted, will show all indexes. + +In this example will show *contents table* only with index above of the position the `.. contents`. + + + +Códigos +======= + +There are two way to write codes in ``rst``, inline and block code. + +Bloco de códigos +---------------- + +Block code are block of the code, to write in ``rst`` follow the template::: + + .. code-block:: `<language>` + :caption: `<caption>` + :name: `<name>` + +Where: + * `<language>`: The language of the code to activate highlight of the syntax. + * `<name>`: The ``name`` directive is like the ``label`` in latex, then is to reference. Must be a + string without space or special characteres. + + +Notes +===== + +Notes are box with text, threre are diferents types of the notes, which changes the color and style. + +Tips +---- + +``tip`` and ``hint`` are used to highlight information that has a positive effect for users, or to +inform a an alternative features. To use ``tip`` or ``hint``. + +Example: tip: +^^^^^^^^^^^^^ + +To use ``tip`` follow this template::: + + .. tip:: + + A note text + +Example: hint: +^^^^^^^^^^^^^^ + +To use ``hint`` follow this template::: + + .. hint:: + + A note text diff --git a/source/pages/application.rst b/source/pages/application.rst index 61dc9c6fc0022ce7e622802ad97165900d689c5c..b8a5a7e6b8564c56874660de60d40dc6a986c8f7 100644 --- a/source/pages/application.rst +++ b/source/pages/application.rst @@ -1,9 +1,10 @@ -########## -Aplicações -########## +################## +Guias e aplicações +################## .. toctree:: :maxdepth: 1 :caption: Aplicações + :glob: - ml.rst + applications/* diff --git a/source/pages/applications/env_management.rst b/source/pages/applications/env_management.rst new file mode 100644 index 0000000000000000000000000000000000000000..9989c3e92becd1c318b179345dd99b65474884c5 --- /dev/null +++ b/source/pages/applications/env_management.rst @@ -0,0 +1,12 @@ +************************* +Gerenciadores de ambiente +************************* + +.. toctree:: + :maxdepth: 3 + :caption: Gerenciadores de ambientes + :glob: + + env_management/* + + diff --git a/source/pages/applications/env_management/python.rst b/source/pages/applications/env_management/python.rst new file mode 100644 index 0000000000000000000000000000000000000000..20f5a7adefa557374eb777dd13622fc7f000909a --- /dev/null +++ b/source/pages/applications/env_management/python.rst @@ -0,0 +1,304 @@ +===================================== +Gerenciadores de ambiente para python +===================================== + +Gerenciadores de ambiente permite que você possua em seu computador ou conta aplicações com +multiplas versões de pacotes e até mesmo diferente versão do intrepetador *python*. + +.. contents:: + :depth: 1 + :local: + + +Virtualenv +---------- + +Virtualenv é um utilitário para criar ambientes python isolado do sistema. Desde a versão ``3.3`` +parte do virtualenv é nativo do python, pelo `módulo venv <https://docs.python.org/3/library/venv.html>`_. + +Instalação +^^^^^^^^^^ +O pacote ``virtualenv`` está disponÃvel tanto em módule, ``module load virtualenv`` quanto é +possÃvel instalar via ``pip``. + +Instalar localmente com ``pip``: +"""""""""""""""""""""""""""""""" +Para instalar via pip no seu usuário execute o comando: ``pip --user install virtualenv``. Exemplo: + +.. code-block:: shell + :caption: Exemplo de instalação do virtualenv + :name: install-virtualenv-local + + [odair@c3hpc:doc/virtualenv ]$ module load python/3.9.7 + [odair@c3hpc:doc/virtualenv ]$ pip install virtualenv + Collecting virtualenv + Downloading virtualenv-20.16.7-py3-none-any.whl (8.8 MB) + |████████████████████████████████| 8.8 MB 7.2 MB/s + Requirement already satisfied: distlib<1,>=0.3.6 in + /home/odair/.local/lib/python3.9/site-packages (from virtualenv) (0.3.6) + Requirement already satisfied: filelock<4,>=3.4.1 in + /home/odair/.local/lib/python3.9/site-packages (from virtualenv) (3.8.0) + Requirement already satisfied: platformdirs<3,>=2.4 in + /home/odair/.local/lib/python3.9/site-packages (from virtualenv) (2.5.2) + Installing collected packages: virtualenv + Successfully installed virtualenv-20.16.7 + [odair@c3hpc:doc/virtualenv ]$ + +É possÃvel conferir se foi instalado e a versão com o comando ``virtualenv --version``, como no +exemplo avaixo: + +.. code-block:: shell + :name: check-virtualenv-version-local + + [odair@c3hpc:doc/virtualenv ]$ virtualenv --version + virtualenv 20.16.7 from /home/odair/.local/lib/python3.9/site-packages/virtualenv/__init__.py + [odair@c3hpc:doc/virtualenv ]$ + +.. note:: + + | Executar o comando ``pip install virtualenv`` vai instalar o ``virtualenv`` na home do seu usuário, dentro do diretório ``${HOME}/local``, então caso não funcione o virtualenv veja se a variável de ambiente ``PATH`` inclui o caminho ``${HOME}/.local/bin/`` caso contrário adicione o comando abaixo: + | ``echo 'PATH=${PATH}:${HOME}/.local/bin' >> ${HOME}/.bashrc && source ${HOME}/.bashrc`` + +Criar ambiente: +^^^^^^^^^^^^^^^ +Para criar um ambiente com ``virtualenv`` use o comando ``virtualenv venv``. Exemplo: + +.. code-block:: shell + :caption: Exemplo de como cirar ambiente com virtualenv + :name: create-env-virtualenv + + [odair@c3hpc:doc/virtualenv ]$ virtualenv venv + created virtual environment CPython3.9.2.final.0-64 in 1767ms + creator CPython3Posix(dest=/home/odair/doc/virtualenv/venv, clear=False, no_vcs_ignore=False, global=False) + seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/home/odair/.local/share/virtualenv) + added seed packages: pip==22.1.2, setuptools==62.3.2, wheel==0.37.1 + activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator + [odair@c3hpc:doc/virtualenv ]$ ls + venv + [odair@c3hpc:doc/virtualenv ]$ + +O virtualenv cria um diretório chamado ``venv`` no qual contêm os arquivos de ativação. + + +Ativar ambiente: +^^^^^^^^^^^^^^^^ +Para ativar o ambiente com virtualenv execute o comando: ``source <env>/bin/activate``, onde `<env>` +é o diretório criado pelo virtualenv, normalmente ele se chama **venv**. Exemplo de ativação: + +.. code-block:: shell + :caption: Exemplo de como ativar virtualenv + :name: activate-virtualenv + + [odair@c3hpc:doc/virtualenv ]$ ls + venv + [odair@c3hpc:doc/virtualenv ]$ source venv/bin/activate + (venv) [odair@c3hpc:doc/virtualenv ]$ + +Note que apareceu ``(venv)`` ao lado da linha de comando, isso indica que você está com o ambiente +ativado. + +Desativar ambiente: +^^^^^^^^^^^^^^^^^^^ +Para desativar o ambiente execute o comando ``deactivate``. Exemplo: + +.. code-block:: shell + :caption: Exemplo de como desativar o virtualenv + :name: deactivate-virtualenv + + (venv) [odair@c3hpc:doc/virtualenv ]$ deactivate + [odair@c3hpc:doc/virtualenv ]$ + +Note que desapareceu ``(venv)`` ao lado da linha de comando, isso indica que o ambiente está desativado. + +Gerenciar pacotes no ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +O `virtualenv` utiliza o `pip` para gerencia os módulos e biblioteca, o único requisito é estar com o ambiente ativado. + +Instalação: +""""""""""" +Para instalar pacotes com ambiente `virtualenv` entre no ambiente e instale normalmente com `pip`. + +Por exemplo para instalar os pacotes pandas e numpy execute a segunte sequência de comandos: + +.. code-block:: shell + :caption: Instalação dos módulos pandas e numpy dentro do ambiente do virtualenv + :name: install-pandas-numpy-virtualenv + + [odair@c3hpc:doc/virtualenv ]$ source venv/bin/activate + (venv) [odair@c3hpc:doc/virtualenv ]$ pip install pandas numpy + Collecting pandas + Downloading pandas-1.5.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.2 MB) + â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â” 12.2/12.2 MB 44.6 MB/s eta 0:00:00 + Collecting numpy + Downloading numpy-1.23.5-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.1 MB) + â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â” 17.1/17.1 MB 45.3 MB/s eta 0:00:00 + Collecting python-dateutil>=2.8.1 + Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB) + Collecting pytz>=2020.1 + Downloading pytz-2022.6-py2.py3-none-any.whl (498 kB) + â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â”â” 498.1/498.1 kB 15.1 MB/s eta 0:00:00 + Collecting six>=1.5 + Using cached six-1.16.0-py2.py3-none-any.whl (11 kB) + Installing collected packages: pytz, six, numpy, python-dateutil, pandas + Successfully installed numpy-1.23.5 pandas-1.5.2 python-dateutil-2.8.2 pytz-2022.6 six-1.16.0 + + [notice] A new release of pip available: 22.1.2 -> 22.3.1 + [notice] To update, run: pip install --upgrade pip + (venv) [odair@c3hpc:doc/virtualenv ]$ + +Para verificar se realmente foi instalado os módulos você pode simplemente executar um arquivo que +importe o módulo ou verificar a versão, como é feito abaixo: + +.. code-block:: python3 + :caption: Verificando se os modulos foram instalados, + :name: virtualenv-check-module-is-installed, + + (venv) [odair@c3hpc:doc/virtualenv ]$ python -c " + import pandas as pd + import numpy as np + print('Versão pandas instalada: ',pd.__version__) + print('Versão numpy instalada: ',np.__version__) + " + Versão pandas instalada: 1.5.2 + Versão numpy instalada: 1.23.5 + (venv) [odair@c3hpc:doc/virtualenv ]$ + + +Remover pacotes: +"""""""""""""""" +Para remover pacotes ative o `virtualenv` e execute o comando `pip uninstall <pacote>` onde `<pacote>` é o nome do módulo que deseja remover. Exemplo: + +.. code-block:: shell + :caption: Remove biblioteca numpy do ambiente + :name: uninstall-numpy-virtual-env + + (venv) [odair@c3hpc:doc/virtualenv ]$ pip uninstall numpy + Found existing installation: numpy 1.23.5 + Uninstalling numpy-1.23.5: + Would remove: + /home/odair/doc/virtualenv/venv/bin/f2py + /home/odair/doc/virtualenv/venv/bin/f2py3 + /home/odair/doc/virtualenv/venv/bin/f2py3.9 + /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy-1.23.5.dist-info/* + /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy.libs/libgfortran-040039e1.so.5.0.0 + /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy.libs/libopenblas64_p-r0-742d56dc.3.20.so + /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy.libs/libquadmath-96973f99.so.0.0.0 + /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy/* + Proceed (Y/n)? y + Successfully uninstalled numpy-1.23.5 + +Veja agora se executar o comando abaixo ele vai dizer que `numpy` não existe, portanto, foi removido. + +.. code-block:: shell + :caption: Verificando se a biblioteca numpy foi removida. + :name: check-numpy-is-uninstalled-virtualenv + + (venv) [odair@c3hpc:doc/virtualenv ]$ python -c " + import numpy as np + print('Versão numpy instalada: ',np.__version__) + " + Traceback (most recent call last): + File "<string>", line 2, in <module> + ModuleNotFoundError: No module named 'numpy' + (venv) [odair@c3hpc:doc/virtualenv ]$ + + +Gerar requeriments.txt +"""""""""""""""""""""" +Para gerar o arquivo `requeriments.txt` entre no ambiente do virtualenv e execute o comando ``pip +freeze > requirements.txt``. Exemplo: + +.. code-block:: shell + :caption: Gerando o arquivo requirements.txt + :name: vitualenv-generate.requirements.txt + + (venv) [odair@c3hpc:doc/virtualenv ]$ pip freeze > requeriments.txt + (venv) [odair@c3hpc:doc/virtualenv ]$ cat requeriments.txt + pandas==1.5.2 + python-dateutil==2.8.2 + pytz==2022.6 + six==1.16.0 + (venv) [odair@c3hpc:doc/virtualenv ]$ + + +Execução de aplicações +^^^^^^^^^^^^^^^^^^^^^^ +O *virtualenv* só permite executação de dentro do ambiente. Então, para rodar aplicações com o +*slurm* e o virtualenv se sugere as seguintes opções: + +.. contents:: + :local: + :depth: 1 + +Ativar o ambiente e executar a aplicação +"""""""""""""""""""""""""""""""""""""""" + +Ativar o ambiente no script `sbatch` +"""""""""""""""""""""""""""""""""""" + +Dicas e recomendações: +^^^^^^^^^^^^^^^^^^^^^^ + +Pipenv +------ + +Criar ambiente: +^^^^^^^^^^^^^^^ + +Ativar ambiente: +^^^^^^^^^^^^^^^^ + +Desativar ambiente: +^^^^^^^^^^^^^^^^^^^ + +Executar aplicações dentro e fora do ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Gerenciar pacotes no ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dicas e recomendações: +^^^^^^^^^^^^^^^^^^^^^^ + +Poetry +------ + +Criar ambiente: +^^^^^^^^^^^^^^^ + +Ativar ambiente: +^^^^^^^^^^^^^^^^ + +Desativar ambiente: +^^^^^^^^^^^^^^^^^^^ + +Executar aplicações dentro e fora do ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Gerenciar pacotes no ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dicas e recomendações: +^^^^^^^^^^^^^^^^^^^^^^ + +Anaconda +-------- + +Criar ambiente: +^^^^^^^^^^^^^^^ + +Ativar ambiente: +^^^^^^^^^^^^^^^^ + +Desativar ambiente: +^^^^^^^^^^^^^^^^^^^ + +Executar aplicações dentro e fora do ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Gerenciar pacotes no ambiente: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dicas e recomendações: +^^^^^^^^^^^^^^^^^^^^^^ + diff --git a/source/pages/applications/machine_learning.rst b/source/pages/applications/machine_learning.rst new file mode 100644 index 0000000000000000000000000000000000000000..c82aa79f631c729e00996c5f5c653eeef7aa7de4 --- /dev/null +++ b/source/pages/applications/machine_learning.rst @@ -0,0 +1,10 @@ +**************** +Machine learning +**************** + +.. toctree:: + :maxdepth: 1 + :caption: Exemplos de aplicações de *Machine learning* + :glob: + + machine_learning/* diff --git a/source/pages/keras.rst b/source/pages/applications/machine_learning/keras.rst similarity index 95% rename from source/pages/keras.rst rename to source/pages/applications/machine_learning/keras.rst index 5ba724e77363b5b7fe9a90c6d7b0515c82d1fb0f..a3972b9dfb688c8b702c1e22c1b5115dccd937e5 100644 --- a/source/pages/keras.rst +++ b/source/pages/applications/machine_learning/keras.rst @@ -122,11 +122,11 @@ Para iniciar um ambiente python com pipenv utilize o comando `pipenv shell`. :caption: iniciando um ambiente python com pipenv :name: pipenv-start-env - [odair@c3hpc:~/deepdream ]$ pipenv shell - Launching subshell in virtual environment... - . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate - [odair@c3hpc:~/deepdream ]$ . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate - deepdream [odair@c3hpc:~/deepdream ]$ + [odair@c3hpc:~/deepdream ]$ pipenv shell + Launching subshell in virtual environment... + . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate + [odair@c3hpc:~/deepdream ]$ . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate + deepdream [odair@c3hpc:~/deepdream ]$ É possÃvel executar código python sem que esteja dentro do ambiente, com o comando `pipenv run <file>` o pipenv vai iniciar o ambiente, executar código contido em `file` e sair do ambiente. diff --git a/source/pages/basic.rst b/source/pages/basic.rst index 40dfe4cea8c0f249da07baa3f8dde9ff484fee0c..bc1136a11e02c8f29147ca4b90584a91872aca79 100644 --- a/source/pages/basic.rst +++ b/source/pages/basic.rst @@ -5,7 +5,6 @@ Primeiros passos .. toctree:: :maxdepth: 1 :caption: Primeiros passos + :glob: - acesso.rst - overview.rst - quickstart.rst + quickstart/* diff --git a/source/pages/ml.rst b/source/pages/ml.rst deleted file mode 100644 index d6675f179fba816d313f83451a96907f4b32104c..0000000000000000000000000000000000000000 --- a/source/pages/ml.rst +++ /dev/null @@ -1,9 +0,0 @@ -**************** -Machine learning -**************** - -.. toctree:: - :maxdepth: 1 - :caption: Primeiros passos - - keras.rst diff --git a/source/pages/acesso.rst b/source/pages/quickstart/acesso.rst similarity index 100% rename from source/pages/acesso.rst rename to source/pages/quickstart/acesso.rst diff --git a/source/pages/overview.rst b/source/pages/quickstart/overview.rst similarity index 99% rename from source/pages/overview.rst rename to source/pages/quickstart/overview.rst index 71a2fc6be7eb2350e1e2d597602a9287f3e714c0..20b1e210e1988ad63172766ca54ec7b8d3fb3982 100644 --- a/source/pages/overview.rst +++ b/source/pages/quickstart/overview.rst @@ -10,7 +10,7 @@ Fluxo de trabalho do HPC O primeiro passo é entender como o cluster e executar programas em computadores de alto desempenho funciona. -.. figure:: ../_static/hpc-slurm.svg +.. figure:: ../../_static/hpc-slurm.svg :alt: Diagrama de funcionamento de computação de alto desempenho. O uso de HPC para realizar processamento paralelo e de alto desempenho consiste em: diff --git a/source/pages/quickstart.rst b/source/pages/quickstart/quickstart.rst similarity index 96% rename from source/pages/quickstart.rst rename to source/pages/quickstart/quickstart.rst index f64fc3ae7e28b594d6639334fb4b5303d53ac4d6..748b3a176ee8d4874f9d4d63ca4f464811a5119d 100644 --- a/source/pages/quickstart.rst +++ b/source/pages/quickstart/quickstart.rst @@ -15,11 +15,9 @@ Principais parâmetros de submissão: * ``-n NUM_PROCESSOS`` Especifica o número de processos a serem iniciados. * ``-N NUM_NODOS`` Especifica que deverão ser alocados pelo menos NUM_NODOS nodos para a execução do job, ou seja, cada nodo vai executar NUM_PROCESSOS dividido por NUM_NODOS. * ``–job-name=NOME`` Especifica o nome do Job que será executado. Este nome irá aparecer juntamente com o id do job na listagem de jobs do sistema. - * ``-e`` Especifica o redirecionamento do stderr. Exemplo: - ``-e arquivoErros.txt`` + * ``-e`` Especifica o redirecionamento do stderr. Exemplo: ``-e arquivoErros.txt`` + * ``-o`` Especifica o redirecionamento do stdout. Caso ``-e`` não tenha sido especificado, stderr também será enviado para o arquivo especificado. Exemplo: ``-o arquivoSaida.txt`` ou ``--output arquivoSaida.txt`` - * ``-o`` Especifica o redirecionamento do stdout. Caso ``-e`` não tenha sido especificado, stderr também será enviado para o arquivo especificado. Exemplo: - ``-o arquivoSaida.txt`` ou ``--output arquivoSaida.txt`` Comando *srun* ============== | O comando ``srun`` submete um *job* para o escalonador, por padrão esse comando é bloqueante. A sintaxe do comando é: @@ -76,7 +74,8 @@ Comando *sbatch* Abaixo, um exemplo de script que roda a aplicação “meuPrograma†que está no diretório bin. A aplicação irá executar por no máximo 7 dias e é solicitado 1 nodo para a execução. .. code-block:: bash - #!/bin/sh + + #!/bin/sh #SBATCH -p 7d #SBATCH -t 7-00:00:00 #SBATCH -n 1