adicao novo manual

source/conf.py

@@ -7,8 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "C3HPC Documentação"
-copyright = "2022, Odair M."
-author = "Odair M."
+copyright = "2025, Bruno S."
+author = "Bruno S."
 release = "0.1.0"
 version = "0.1.0"
 

source/pages/manual-usuario-c3hpc.md

+<div style="text-align: center;">
+    <img src="../_static/c3sl_logo.svg" alt="Logo do C3HPC" style="width: 200px;">
+    <img src="../_static/root-logo.png" alt="Logo dos roots" style="width: 200px;">
+</div>
+
+# Manual do usuário -  C3HPC 
+Este documento contém todas as informações necessárias para a utilização plena dos usuários do C3HPC.
+
+Informações mais aprofundadas sobre o funcionamento do SLURM ou do Anaconda devem ser consultadas nos repositórios de documentação do [SLURM](https://slurm.schedmd.com/documentation.html) e do [Anaconda3](https://www.anaconda.com/docs/main)
+
+## Solicitando abertura de conta no C3HPC:
+
+Favor enviar sua solicitação para [c3hpc@inf.ufpr.br](mailto:c3hpc@inf.ufpr.br) endereço eletrônico. Sua solicitação será analisada e você receberá uma resposta em **até** 7 dias úteis. Cabe ao C3SL liberar ou não o uso do C3HPC para usuários externos ao DInf-UFPR, visando manter a disponibilidade de recursos aos utentes já cadastrados.
+
+- Junto da sua solicitação de criação de conta, envie os seguintes dados:
+    - Nome Completo.
+    - Organização que faz parte (nome do projeto, departamento, entidade, etc).
+    - Informação de contato (email).
+    - Tempo de vida da conta (por quanto tempo utilizará os recursos do cluster)
+    - Quais recursos utilizará (somente CPU, GPU, alto uso de RAM, etc).
+    - Chave SSH pública (no padrão ED25519) 
+
+- Sob **nenhuma** hipótese será criada uma conta de usuário com poderes administrativos (sudoer) sobre o C3HPC sem autorização expressa da diretoria do C3SL.
+- Para usuários internos do DInf - UFPR serão aceitas somente chaves ssh da máquina 'macalan'. Não serão adicionadas chaves de outra máquina, mesmo que seja local do DInf - UFPR.
+- O seu usuário fará parte de um grupo que tem acesso somente aos recursos solicitados. Também existem filas prioritárias que são definidas de acordo com as políticas e demandas do C3SL. O mesmo reserva o direito de alterar quaisquer configurações de alocação de recursos sem aviso prévio.
+
+## Acessando sua conta no C3HPC
+
+Após a confirmação da criação da sua conta no C3HPC, você terá acesso ao nó de login do C3HPC. Para acessar e começar a utilizar os sistemas você precisará de uma máquina com um cliente SSH configurado.
+
+O acesso pode ser feito com o seguinte comando: `ssh <seu_usuario>@c3hpc.c3sl.ufpr.br` e você verá a seguinte tela:
+```sh
+<seu_usuario_local>@<sua_maquina_local>:~$ ssh <seu_usuario>@c3hpc.c3sl.ufpr.br
+
+       ██╗ ██████╗██████╗ ██╗  ██╗██████╗  ██████╗
+      ██╔╝██╔════╝╚════██╗██║  ██║██╔══██╗██╔════╝
+     ██╔╝ ██║      █████╔╝███████║██████╔╝██║
+    ██╔╝  ██║      ╚═══██╗██╔══██║██╔═══╝ ██║
+██╗██╔╝   ╚██████╗██████╔╝██║  ██║██║     ╚██████╗
+╚═╝╚═╝     ╚═════╝╚═════╝ ╚═╝  ╚═╝╚═╝      ╚═════╝
+
+Bem-vindo ao Computador de Alto Desempenho do
+Centro de Computação Científica e Software Livre.
+
+Esta máquina possui recursos limitados e é destinada
+somente para submissão de jobs para o SLURM.
+
+Mais informações sobre o funcionamento desta podem
+ser encontradas na página do suporte em:
+
+https://c3hpc.docs.c3sl.ufpr.br/
+<seu_usuario>@c3hpc:~$ 
+```
+- Note que não foi solicitado senha pois, por questões de segurança, a autenticação de acesso será feita somente com a chave ssh ed25519 fornecida no momento da solicitação da criação de contas. O usuário também não conseguirá 'criar' ou alterar a sua senha, visto que este recurso está desativado no servidor de autenticação.
+
+Pronto! Você está logado e pronto para utilizar o C3HPC.
+
+## Administrando sua conta no C3HPC
+### O(s) seu(s) ambiente(s) Conda
+O sistema conta com uma instalação do Anaconda3 para todos os usuários. O comando 'conda' está disponivel no PATH universal do sistema, não sendo necessário que o usuário faça sua própria instalação do anaconda3.
+
+- Casos isolados de pacotes que, por ventura, não estejam disponíveis nos repositórios do Anaconda3 terão que ser solicitados aos roots via [email](mailto:c3hpc@inf.ufpr.br).
+
+As contas do C3HPC não tem senha. O usuário logará na máquina utilizando somente sua chave SSH pública.
+
+O usuário deve criar o seu ambiente virtual conda com o seguinte comando: `conda create -n <nome_do_ambiente>`
+
+O ambiente conda criado ficará armazenado dentro da $HOME do usuário, em: `~/$USER/.conda/envs/<nome_do_ambiente>`
+
+Para 'entrar' no seu ambiente virtual utilize o comando: `conda activate <nome_do_ambiente>`
+
+Para 'sair' do seu ambiente virtual utilize o comando: `conda deactivate <nome_do_ambiente>`
+
+O usuário tem total liberdade para instalar quaisquer pacotes dentro do seu ambiente Conda utilizando o comando `conda install -c <canal_do_pacote> <nome_do_pacote>`
+    
+    O Anaconda organiza os pacotes em repositórios, então, muito provavelmente, será necessário buscar em qual canal o pacote desejado está disponível. 
+
+### O seu armazenamento no C3HPC
+O C3HPC conta com 80TB de armazenamento total para ser **compartilhado** entre os usuários. Atente-se quanto a arquivos duplicados no sistema, estes ocupam espaço que seu colega pode vir a precisar.
+
+    A administração do C3HPC, assim como o C3SL, abstém-se da responsabilidade de manutenção da integridade dos dados dos usuários do C3HPC. Caso o sistema de arquivos venha a falhar e informação seja perdida, a mesma poderá não ser recuperada. Cabe somente ao usuário manter um backup dos seus dados em um local que julgue seguro.
+
+## Características técnicas do C3HPC
+
+Um cluster computacional é conjunto de computadores escravos coordenados por um mestre (no caso do C3HPC é o `c3hpc-headnode`), com o propósito de compartilhar seus recursos e processar grandes volumes de dados de maneira paralela e em alta velocidade. Estas máquinas comunicam-se entre si através de uma rede de alta velocidade.
+
+![Ilustracao cluster](../_static/cluster.webp)
+
+Os nós escravos do C3HPC tem as seguintes configurações:
+
+### Nós de Processamento:
+| Nó | RAM | CPU | Cores | Disco de scratch? | GPU? | Conexão |
+| -- | --- | --- | ----- | ----------------- | ---- | ------- |
+| node[2-7] | 200GB | Intel(R) Xeon(R) CPU E5-2683 v4 @ 2.10GHz | 32 | Sim, 8TB | Não | ETH 1Gbps |
+| proc[1-2] | 500GB | Intel(R) Xeon(R) CPU E5-2683 v4 @ 2.10GHz | 64 | Sim, 8TB | Não | ETH 1Gbps |
+| pti | 500GB | Intel(R) Xeon(R) CPU E5-2683 v4 @ 2.10GHz | 64 | Sim, 450GB | Não | ETH 1Gbps |
+| vti1 | 180GB | Intel(R) Xeon(R) Silver 4110 CPU @ 2.10GHz | 32 | Sim, 450GB | 4x NVIDIA Tesla V100 32GB | ETH 1Gbps |
+| vti2 | 150GB | Intel(R) Xeon(R) Silver 4110 CPU @ 2.10GHz | 32 | Sim, 450GB | 4x NVIDIA Tesla V100 32GB | ETH 1Gbps |
+
+O usuário pode conferir as características das partições com o comando `scontrol show partition <nome_partição>`. O mesmo vale para imprimir as configurações de um nó específico, com o comando: `scontrol show node <nome_do_nó>`
+
+### Nó Controlador:
+O controlador do C3HPC não é acessível por usuários, mas é quem armazena todas as informações. Este possui as seguintes características:
+
+| RAM | Cores | Armazenamento | Conexão |
+| --- | ----- | ------------- | ------- |
+| 256GB | 40 | JBOD 12Gbps em RAIDZ60 totalizando 80TB | SFP+ 10Gbps |
+
+## Utilizando o SLURM para administrar seus jobs:
+
+A natureza de um cluster é ser um sistema robusto e **compartilhado** entre **vários** clientes, logo, o usuário deve conferir e alocar somente aquilo que irá utilizar. O SLURM aloca e bloqueia o recurso solicitado para aquele job, mesmo que não seja, de fato, utilizado. Logo, cabe ao usuário provisionar os recursos que irá utilizar.
+
+Todos os nós do C3HPC tem um disco de scratch montado em `/scratch`. Recomenda-se que o usuário crie um diretório dentro deste disco para **copiar temporariamente** seus datasets. Este comportamento evita sobrecarga no NFS (Network File System) do sistema, que é consideravelmente lento em comparação com um disco local.
+
+### Verificando a disponibilidade de recursos:
+
+O usuário pode ter um panorama simplificado sobre o status do sistema em tempo real com o comando `sinfo`. Aqui esta um exemplo de saída deste:
+```shell
+root@c3hpc-headnode:~# sinfo
+PARTITION        AVAIL  TIMELIMIT  NODES  STATE NODELIST
+cpu*                up 7-00:00:00      2    mix proc[1-2]
+cpu*                up 7-00:00:00      6  alloc node[2-7]
+cpu-test            up      10:00      2    mix proc[1-2]
+cpu-test            up      10:00      6  alloc node[2-7]
+cpu-24h             up 1-00:00:00      2    mix proc[1-2]
+cpu-24h             up 1-00:00:00      6  alloc node[2-7]
+Family-node         up 7-00:00:00      6  alloc node[2-7]
+Family-node-test    up      10:00      6  alloc node[2-7]
+Family-node-24h     up 1-00:00:00      6  alloc node[2-7]
+Family-proc         up 7-00:00:00      2    mix proc[1-2]
+Family-proc-test    up      10:00      2    mix proc[1-2]
+Family-proc-24h     up 1-00:00:00      2    mix proc[1-2]
+Family-pti          up 7-00:00:00      1   idle pti
+Family-pti-test     up      10:00      1   idle pti
+Family-pti-24h      up 1-00:00:00      1   idle pti
+Family-vti          up 7-00:00:00      1    mix vti1
+Family-vti          up 7-00:00:00      1   idle vti2
+Family-vti-test     up      10:00      1    mix vti1
+Family-vti-test     up      10:00      1   idle vti2
+Family-vti-24h      up 1-00:00:00      1    mix vti1
+Family-vti-24h      up 1-00:00:00      1   idle vti2
+gpu                 up 5-00:00:00      1    mix vti1
+gpu                 up 5-00:00:00      2   idle pti,vti2
+gpu-test            up      10:00      1    mix vti1
+gpu-test            up      10:00      2   idle pti,vti2
+```
+Aqui podemos ver que os nós estão em estados diferentes, com alguns completamente alocados (alloc), parcialmente alocados (mix) e ociosos (idle).
+
+- Uma das características que os administradores do C3HPC impuseram foi limitar o usuário a utilizar somente filas com recursos que foram solicitados. Usuários que não solicitaram uso de GPU, não terão acesso as filas de máquinas que dispõe desta característica.
+- Grupos de usuários e prioridades para utilização das máquinas também foram definidas com base nas políticas internas de utilização do C3SL. Tais políticas podem ser revistas e alteradas sem aviso prévio.
+- Quaisquer dúvidas sobre a utilização dos recursos alocados para o seu usuário podem ser enviadas para [c3hpc@inf.ufpr.br](mailto:c3hpc@inf.ufpr.br).
+
+Informações mais aprofundadas do comando `sinfo` podem ser encontradas [aqui](https://slurm.schedmd.com/sinfo.html).
+
+### Entendendo as filas
+O C3HPC está organizado da seguinte maneira:
+
+    - Filas para processamento somente em CPU.
+    - Filas para processamento utilizando GPU.
+    - Filas por família de máquina.
+- Todos os 'sabores' de filas tem as seguintes subdivisões:
+    - Uma fila de alta fatia de tempo (7 dias para CPU e 5 dias para GPU).
+    - Uma fila para teste do seu código (com 10 minutos de limite).
+    - Uma fila de 24 horas para jobs envolvendo processamento em CPU.
+
+As filas de 'Family' são destinadas a experimentos que necessitam processamento em hardware homogêneo, como benchmarks. 
+
+
+### Submetendo seus jobs para o SLURM
+
+Os jobs podem ser enviados com o comando `sbatch`, mais informações sobre a formatação do documento podem ser encontradas [aqui](https://slurm.schedmd.com/sbatch.html).
+
+   - É importante verificar se você está "dentro" do seu ambiente conda **antes** de submeter o seu job. Caso o ambiente esteja faltando ou errado, as bibliotecas podem nao ser encontradas e o seu batch não funcionará.
+
+O script de submissão no formato `.sbatch` deverá conter somente os comandos para outros scripts. Exemplo:
+
+```sh
+#!/bin/sh
+
+#SBATCH -p cpu
+#SBATCH --job-name=exemplo
+#SBATCH -n 1
+#SBATCH -o ./output
+#SBATCH -c 16
+#SBATCH --mem=20g
+
+mkdir /scratch/$USER
+cp -r $HOME/dataset /scratch/$USER/
+srun script.sh
+srun script2.sh
+```
+
+Neste `script.sbatch` o usuário enviou o seu `script1.sh` e `script2.sh` (que são arquivos **externos** ao `script.sbatch`) para uma alocação de `16 cores` na partição `cpu`, com identificação `exemplo`, em 1 único nó, encaminhando a saída para o arquivo `output` e com um uso total de `20GB` de memória RAM. Em adição aos comandos do SLURM, também efetuamos a cópia do dataset usado no processamento para o disco local do nó alocado.
+
+Existem políticas de penalização automática para usuários que alocam recursos de maneira imprópria, implicando em queda de prioridade na execução dos jobs. Dimensione bem os recursos que pretende utilizar para que não seja penalizado.
+
+### Monitorando seus jobs:
+
+O comando `squeue` mostra os jobs que estão rodando no cluster. Um exemplo de saida do comando `squeue` é:
+```shell
+root@c3hpc:~# squeue
+             JOBID PARTITION     NAME     USER ST       TIME  NODES NODELIST(REASON)
+               103    gpu      NAS-NPB    root R        53:10   1       vti1
+root@c3hpc:~# 
+```
+
+Mais informações sobre o comando `squeue` podem ser encontradas [aqui](https://slurm.schedmd.com/squeue.html).
+
+## Boas práticas em um ambiente computacional compartilhado:
+
+Um ambiente computacional compartilhado demanda que todos adotem um comportamento diplomático, com o intuito de respeitar os processos dos seus colegas e não causar indisponibilidade de recursos.
+
+- Priorize o uso do `sbtach` para submeter o seu job. Revise a alocação de recursos antes de submetê-lo. Utilizando o `sbatch` o nó alocado será liberado assim que a tarefa for concluída, para que fique livre para outros usuários.
+- Configure o email para que o cluster te avise quando seu job terminar.
+- Seja consciente quando a alocação de recursos: procure solicitar somente aquilo que seu experimento for, de fato, utilizar. Exemplo: não aloque a partição `gpu` para jobs que utilizarão somente CPU, para isso existe a partição `cpu`.
+- Como definição de segurança, somente os administradores do C3HPC tem acesso direto aos nós, o usuário não conseguirá acessar os mesmos via `ssh`.
+- A máquina de login (denominada `c3hpc`) é destinada somente para a submissão de jobs para o SLURM e administração do ambiente `conda` do usuário. Esta possui limites rígidos e **não** deve ser usada para processamento.
+- Utilize o disco local montado em `/scratch` para copiar seus datasets.
+- Qualquer dúvida não coberta por este documento ou pela documentação das ferramentas SLURM e Anaconda, não hesite em mandar um email para o suporte do C3HPC (c3hpc@inf.ufpr.br).