spack-stack-inpe

Repositório de configurações institucionais do INPE para uso com o spack-stack, com foco atual na máquina EGEON.

Atualmente, este repositório disponibiliza as configurações de site e o template necessários para a criação do ambiente mpas-bundle na EGEON. A configuração para a máquina JACI está em desenvolvimento e será incorporada futuramente à mesma estrutura.

Sumário

Visão geral
Objetivo
Escopo atual do repositório
Estrutura do repositório
Arquitetura do repositório
Requisitos
Fluxo rápido
Instalação manual
Uso dos módulos após a instalação
Indicadores de sucesso
Verificação pós-instalação
Testes funcionais
Script automatizado
Ativação do ambiente após a instalação
Ambiente compartilhado para o grupo
Boas práticas de execução
Problemas comuns e soluções
Informações que ainda precisam ser complementadas
Licença

Visão geral

O spack-stack-inpe concentra arquivos de configuração institucionais do INPE para uso com o spack-stack, permitindo adaptar a instalação padrão ao ambiente computacional local.

No estado atual do projeto, o repositório contém a configuração da EGEON e o template de ambiente mpas-bundle. A configuração da JACI está em preparação e será integrada futuramente.

Objetivo

Este repositório tem como objetivo:

padronizar a configuração do spack-stack no ambiente institucional do INPE;
reduzir erros recorrentes de instalação e concretização;
facilitar a criação e reutilização do ambiente mpas-bundle;
registrar um procedimento reprodutível de instalação, validação e ativação do ambiente;
servir de base para projetos científicos e técnicos que dependam desse ecossistema, como o MPAS-JEDI.

Escopo atual do repositório

No momento, o repositório contém:

configurações de site para a EGEON;
template de ambiente mpas-bundle;
documentação do processo manual de instalação;
referência ao fluxo automatizado de instalação e testes.

Observação importante

A documentação manual abaixo usa como referência o spack-stack 1.7.0.
O fluxo automatizado permite parametrizar a versão do spack-stack por meio da variável de ambiente SPACK_VERSION.
A configuração da JACI ainda não está incluída nesta versão do repositório.

Estrutura do repositório

A estrutura esperada deste repositório é:

configs/
├── sites/
│   └── egeon/
└── templates/
    └── mpas-bundle/

Descrição dos diretórios

configs/sites/egeon/: arquivos de configuração específicos da máquina EGEON;
configs/templates/mpas-bundle/: template do ambiente mpas-bundle.

Quando a configuração da JACI estiver pronta, a estrutura do diretório configs/sites/ deverá ser expandida de forma consistente.

Arquitetura do repositório

Este repositório segue uma separação explícita entre:

infraestrutura da máquina (site)
definição da aplicação (template)
descoberta automática do ambiente (bootstrap)

Essa separação é fundamental para garantir reprodutibilidade, portabilidade e consistência institucional.

Relação entre `.env`, `site` e `template`

O fluxo completo é:

.env → bootstrap → site → template → ambiente final

Componentes

1. Bootstrap (`scripts/bootstrap/`)

Responsável por descobrir automaticamente o ambiente da máquina.

env/<machine>.env: define o ambiente mínimo da máquina
bootstrap_spack_site.sh: gera automaticamente:
- compilers.yaml
- packages.yaml

O .env deve conter apenas o mínimo necessário para que o Spack entenda a máquina.

Para detalhes completos, consulte:

scripts/bootstrap/env/README.md

2. Site (`configs/sites/<machine>/`)

Define a configuração institucional da máquina.

Exemplo:

configs/sites/egeon/

Contém:

compilers.yaml → compiladores disponíveis
packages.yaml → externals e providers
modules.yaml → estrutura de módulos
config.yaml → configuração geral do Spack

Interpretação importante

O diretório configs/sites/<machine>/ representa uma configuração escolhida em um determinado momento.

Ou seja:

é uma fotografia da máquina
pode ser atualizada a qualquer momento
deve ser regenerada quando o ambiente da máquina mudar

Como atualizar um site

Ajustar o .env correspondente
Executar o bootstrap:

./bootstrap_spack_site.sh --site <machine>

Revisar os arquivos gerados
Atualizar configs/sites/<machine>/

3. Template (`configs/templates/`)

Define o ambiente da aplicação.

Exemplo:

configs/templates/mpas-bundle/spack.yaml

Esse arquivo define:

dependências do MPAS-JEDI
bibliotecas científicas
configuração do ambiente

O template é comum a todas as máquinas.

Regra crítica

O site NÃO deve conter dependências do MPAS-BUNDLE.

Essas dependências já estão no template:

configs/templates/mpas-bundle/spack.yaml

Interpretação prática

Componente	Função
`.env`	descobrir a máquina
`site/`	definir a infraestrutura
`template/`	definir a aplicação
Spack	montar o ambiente final

Resultado final

site (máquina)
+
template (mpas-bundle)
=
ambiente completo MPAS-JEDI

Requisitos

Antes de iniciar a instalação, confirme os seguintes requisitos:

acesso ao sistema de arquivos em /mnt/beegfs/$USER;
git disponível no ambiente;
sistema de módulos em funcionamento;
módulo gnu9 disponível na EGEON;
acesso ao GitHub para clonagem dos repositórios;
permissões adequadas para criar diretórios e instalar pacotes no espaço de trabalho do usuário.

Fluxo rápido

Para usuários experientes, o fluxo mínimo de instalação manual na EGEON, usando o spack-stack 1.7.0, é o seguinte:

cd /mnt/beegfs/$USER

rm -rf ~/.cache/spack ~/.spack

git clone https://github.com/JCSDA/spack-stack -b release/1.7.0 spack-stack_1.7.0 --recurse-submodules
git clone https://github.com/GAD-DIMNT-CPTEC/spack-stack-inpe.git

module load gnu9

cd spack-stack_1.7.0
source setup.sh

cp -r ../spack-stack-inpe/configs/sites/egeon configs/sites/
cp -r ../spack-stack-inpe/configs/templates/mpas-bundle configs/templates/

spack stack create env --name=mpas-bundle --template=mpas-bundle --site=egeon

cd envs/mpas-bundle
spack env activate .

spack concretize 2>&1 | tee log.concretize
spack install --source 2>&1 | tee log.install
spack module lmod refresh -y 2>&1 | tee log.modules
spack stack setup-meta-modules 2>&1 | tee log.metamodules

Após a instalação, para utilizar os módulos gerados:

module use /mnt/beegfs/$USER/spack-stack_1.7.0/envs/mpas-bundle/install/modulefiles/Core
module load stack-gcc/9.4.0

Importante: este fluxo rápido refere-se ao procedimento manual atual com foco na EGEON. Para a instalação automatizada e para a seleção parametrizada da versão do Spack-Stack, utilize o script apropriado.

Instalação manual

O procedimento abaixo descreve a instalação manual do ambiente com base no spack-stack 1.7.0.

0. Pré-requisitos

Antes de iniciar, certifique-se de que:

o comando module está disponível no sistema;
o compilador/base esperada para o site egeon pode ser carregada com module load gnu9;
o git está disponível;
há acesso ao filesystem compartilhado em /mnt/beegfs/$USER;
o repositório institucional spack-stack-inpe está acessível.

1. Preparação do diretório de trabalho

Recomenda-se executar todo o procedimento em beegfs:

cd /mnt/beegfs/$USER

2. Limpeza de cache e configuração local

Antes de iniciar, recomenda-se limpar caches e configurações locais anteriores do Spack:

rm -rf ~/.cache/spack
rm -rf ~/.spack

Atenção: esse procedimento remove caches e configurações locais do Spack do usuário atual. Recomenda-se especialmente quando houve tentativas anteriores de instalação ou alterações nos arquivos de configuração.

3. Clone do spack-stack

Clone a versão de referência do spack-stack com submódulos:

git clone https://github.com/JCSDA/spack-stack -b release/1.7.0 spack-stack_1.7.0 --recurse-submodules

Carregue o compilador disponível na EGEON:

module load gnu9

Entre no diretório clonado e inicialize o ambiente:

cd spack-stack_1.7.0
source setup.sh

4. Clone deste repositório e cópia das configurações

Clone este repositório:

git clone https://github.com/GAD-DIMNT-CPTEC/spack-stack-inpe.git

Em seguida, copie os arquivos de configuração de site e o template para dentro da árvore do spack-stack:

cp -r spack-stack-inpe/configs/sites/egeon spack-stack_1.7.0/configs/sites/
cp -r spack-stack-inpe/configs/templates/mpas-bundle spack-stack_1.7.0/configs/templates/

Importante: atualmente este repositório disponibiliza apenas a configuração da EGEON.

5. Verificação do `compilers.yaml`

Abra o arquivo:

spack-stack_1.7.0/configs/sites/egeon/compilers.yaml

Verifique se a chave flags está presente dentro da definição do compilador.

Exemplo esperado:

compilers:
  - compiler:
      spec: gcc@9.4.0
      paths:
        cc: /path/to/gcc
        cxx: /path/to/g++
        f77: /path/to/gfortran
        fc: /path/to/gfortran
      flags: {}

A ausência de flags: {} pode causar falhas no comando spack concretize.

6. Criação e ativação do ambiente

Crie o ambiente mpas-bundle com o template e o site configurados:

spack stack create env --name=mpas-bundle --template=mpas-bundle --site=egeon
cd envs/mpas-bundle

Ative o ambiente criado:

spack env activate .

7. Concretização, instalação e meta-módulos

Concretize o ambiente e registre a saída em log:

spack concretize 2>&1 | tee log.concretize

Instale os pacotes:

spack install  --source 2>&1 | tee log.install

A opção --source também preserva os códigos-fonte instalados, o que pode ser útil para rastreabilidade e depuração.

Gere ou atualize os módulos Lmod do ambiente:

spack module lmod refresh -y 2>&1 | tee log.modules

Esse passo atualiza os módulos Lmod correspondentes aos pacotes instalados no ambiente.

Gere os meta-módulos:

spack stack setup-meta-modules 2>&1 | tee log.metamodules

Os meta-módulos facilitam o carregamento posterior do ambiente, organizando de forma mais simples o uso dos módulos gerados.

Uso dos módulos após a instalação

Para utilizar os módulos compilados:

module use /mnt/beegfs/$USER/spack-stack_1.7.0/envs/mpas-bundle/install/modulefiles/Core
module load stack-gcc/9.4.0

Para listar os módulos disponíveis:

module avail

Alguns módulos adicionais ficam disponíveis apenas após carregar o OpenMPI:

module load openmpi/4.1.1

Indicadores de sucesso

Os principais sinais de que a instalação ocorreu corretamente são:

Mensagens de sucesso nos logs, por exemplo:
```
Successfully installed <package-name>
```
Criação do diretório de módulos no ambiente instalado.
Geração dos arquivos de log:
- log.concretize
- log.install
- log.metamodules
Reconhecimento adequado de dependências externas e módulos carregados.

Verificação pós-instalação

Após a instalação, recomenda-se executar:

spack env activate .
spack find
ls -1 log.concretize log.install log.metamodules

Se necessário, consulte logs adicionais do Spack em:

<spack-stack-dir>/cache/log/

Testes funcionais

Os testes abaixo ajudam a validar bibliotecas críticas do ambiente.

Antes dos testes, exporte os caminhos das bibliotecas principais:

export NETCDF_DIR=$(spack location -i netcdf-c)
export NETCDF_CXX_DIR=$(spack location -i netcdf-cxx4)
export HDF5_DIR=$(spack location -i hdf5)

if [ -d "$NETCDF_DIR" ]; then
    export LD_LIBRARY_PATH="$NETCDF_DIR/lib:$LD_LIBRARY_PATH"
fi

if [ -d "$NETCDF_CXX_DIR" ]; then
    export LD_LIBRARY_PATH="$NETCDF_CXX_DIR/lib:$LD_LIBRARY_PATH"
fi

if [ -d "$HDF5_DIR" ]; then
    export LD_LIBRARY_PATH="$HDF5_DIR/lib:$LD_LIBRARY_PATH"
fi

Teste NetCDF

Crie o arquivo de teste:

cat <<EOF > test_netcdf.c
#include <netcdf.h>
#include <stdio.h>

int main() {
    int ncid, retval;
    const char *filename = "test.nc";

    if ((retval = nc_create(filename, NC_CLOBBER, &ncid)))
        return retval;

    if ((retval = nc_close(ncid)))
        return retval;

    if ((retval = nc_open(filename, NC_NOWRITE, &ncid)))
        return retval;

    printf("NetCDF test passed. File '%s' created and opened successfully.\n", filename);
    return 0;
}
EOF

Compile e execute:

gcc test_netcdf.c -o test_netcdf -I$NETCDF_DIR/include -L$NETCDF_DIR/lib -lnetcdf
./test_netcdf

Saída esperada:

NetCDF test passed. File 'test.nc' created and opened successfully.

Teste NetCDF-C++

Crie o arquivo de teste:

cat <<EOF > test_netcdf_cxx.cpp
#include <netcdf>
#include <iostream>

int main() {
    try {
        std::string filename = "test_cxx.nc";
        netCDF::NcFile dataFile(filename, netCDF::NcFile::replace);
        std::cout << "NetCDF-C++ test passed. File '" << filename << "' created successfully." << std::endl;
    } catch (netCDF::exceptions::NcException& e) {
        std::cerr << "NetCDF-C++ test failed: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}
EOF

Compile e execute:

g++ test_netcdf_cxx.cpp -o test_netcdf_cxx \
    -I$NETCDF_CXX_DIR/include -L$NETCDF_CXX_DIR/lib \
    -I$NETCDF_DIR/include -L$NETCDF_DIR/lib \
    -lnetcdf_c++4
./test_netcdf_cxx

Saída esperada:

NetCDF-C++ test passed. File 'test_cxx.nc' created successfully.

Teste HDF5

Crie o arquivo de teste:

cat <<EOF > test_hdf5.c
#include "hdf5.h"
#include <stdio.h>

int main() {
    hid_t file_id;
    herr_t status;

    file_id = H5Fcreate("test.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
    if (file_id < 0) {
        printf("Error creating HDF5 file.\n");
        return 1;
    }

    status = H5Fclose(file_id);
    if (status < 0) {
        printf("Error closing HDF5 file.\n");
        return 1;
    }

    printf("HDF5 test passed. File 'test.h5' created successfully.\n");
    return 0;
}
EOF

Compile e execute:

gcc test_hdf5.c -o test_hdf5 -I$HDF5_DIR/include -L$HDF5_DIR/lib -lhdf5
./test_hdf5

Saída esperada:

HDF5 test passed. File 'test.h5' created successfully.

Teste OpenMPI

Crie o arquivo de teste:

cat <<EOF > test_mpi.c
#include <mpi.h>
#include <stdio.h>

int main(int argc, char *argv[]) {
    MPI_Init(&argc, &argv);

    int rank, size;
    MPI_Comm_rank(MPI_COMM_WORLD, &rank);
    MPI_Comm_size(MPI_COMM_WORLD, &size);

    printf("Hello from rank %d of %d.\n", rank, size);

    MPI_Finalize();
    return 0;
}
EOF

Compile e execute:

mpicc test_mpi.c -o test_mpi
mpirun -np 4 ./test_mpi

Saída esperada:

Hello from rank 0 of 4.
Hello from rank 1 of 4.
Hello from rank 2 of 4.
Hello from rank 3 of 4.

Script automatizado

O fluxo automatizado executa, de forma encadeada, as etapas de:

limpeza de cache e variáveis de ambiente;
clone do spack-stack;
cópia das configurações de site e template;
criação e ativação do ambiente;
concretização e instalação;
geração de meta-módulos;
configuração do ambiente para testes;
testes de NetCDF, NetCDF-C++, HDF5 e OpenMPI;
geração de um script auxiliar de ativação.

Observações importantes sobre a automação

O passo a passo manual deste README usa como exemplo o spack-stack 1.7.0.
No fluxo automatizado, a versão do Spack-Stack pode ser parametrizada por SPACK_VERSION.
O script atual ainda contém referências legadas ao nome spack-egeon; essa nomenclatura deverá ser atualizada para refletir o nome oficial spack-stack-inpe.

Exemplo conceitual de uso

Quando o script estiver ajustado para o nome definitivo do repositório, a ideia é permitir algo como:

export SPACK_VERSION=1.7.0
./install_and_test_spack_stack.sh

ou equivalente ao mecanismo de parametrização adotado na versão final do script.

Ativação do ambiente após a instalação

Ao final da automação, pode ser gerado um script auxiliar chamado start_spack_bundle.sh, utilizado para ativar corretamente o ambiente instalado.

Exemplo de ativação:

source $HOME/.spack/mpas-bundle/start_spack_bundle.sh

Esse script deve ser usado para:

ativar o ambiente mpas-bundle;
adicionar o caminho correto de módulos;
carregar módulos essenciais;
complementar variáveis de ambiente necessárias, como LD_LIBRARY_PATH.

Importante: esse passo deve ser executado sempre que o ambiente instalado for utilizado em uma nova sessão.

Ambiente compartilhado para o grupo

Para evitar instalações duplicadas por usuário, recomenda-se utilizar um ambiente compartilhado já instalado em diretório comum, por exemplo:

/mnt/beegfs/das.group/spack-stack_1.7.0/envs/mpas-bundle/

Se houver um script de ativação compartilhado, o uso esperado é:

source /mnt/beegfs/das.group/spack-envs/mpas-bundle/start_spack_bundle.sh

Benefícios dessa abordagem:

uniformidade entre usuários;
redução de consumo de disco;
menor risco de divergência entre ambientes;
maior facilidade para uso colaborativo.

Boas práticas de execução

execute a instalação em um diretório estável no beegfs;
registre a saída dos comandos principais em arquivos de log;
revise compilers.yaml antes da concretização;
valide o ambiente com testes mínimos antes de iniciar compilações maiores;
use um ambiente compartilhado quando a equipe precisar trabalhar com a mesma pilha de software;
mantenha documentadas a versão do spack-stack, o compilador utilizado e o conjunto de módulos carregados.

Problemas comuns e soluções

1. Erro relacionado a `flags` ausente no `compilers.yaml`

Descrição: o spack concretize pode falhar se a chave flags estiver ausente.

Solução: adicione:

flags: {}

2. Falha no `spack stack setup-meta-modules`

Descrição: pode ocorrer por ativação incorreta do ambiente ou configuração inconsistente do sistema de módulos.

Solução: confirme:

se o ambiente foi ativado corretamente;
se os arquivos do site foram copiados para os diretórios esperados;
se o MODULEPATH está coerente com a instalação realizada.

3. Bibliotecas dinâmicas não encontradas em tempo de execução

Descrição: binários de teste podem falhar com mensagens relacionadas a libnetcdf.so ou libhdf5.so.

Solução: complemente LD_LIBRARY_PATH com os caminhos retornados por:

spack location -i netcdf-c
spack location -i netcdf-cxx4
spack location -i hdf5

4. Problemas com OpenMPI e ambiente local

Descrição: algumas combinações entre MPI, módulos locais e ambiente do usuário podem causar comportamento inconsistente.

Solução: priorize os módulos previstos no ambiente instalado e valide o teste MPI antes de seguir para compilações maiores.

Informações que ainda precisam ser complementadas

Os itens abaixo ainda devem ser confirmados ou ajustados no repositório:

caminho e versão final do script automatizado após a renomeação definitiva para spack-stack-inpe;
inclusão futura da configuração da JACI;
definição formal da licença do projeto;
confirmação do local definitivo do ambiente compartilhado e do script de ativação compartilhado;
sincronização completa entre o README e a versão final do script automatizado.

Licença

Informação ainda não definida neste README.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
configs		configs
docs		docs
.gitignore		.gitignore
README.md		README.md
install_and_test_spack_stack.sh		install_and_test_spack_stack.sh
start_spack_bundle.sh		start_spack_bundle.sh

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

spack-stack-inpe

Sumário

Visão geral

Objetivo

Escopo atual do repositório

Observação importante

Estrutura do repositório

Descrição dos diretórios

Arquitetura do repositório

Relação entre .env, site e template

Componentes

1. Bootstrap (scripts/bootstrap/)

2. Site (configs/sites/<machine>/)

Interpretação importante

Como atualizar um site

3. Template (configs/templates/)

Regra crítica

Interpretação prática

Resultado final

Requisitos

Fluxo rápido

Instalação manual

0. Pré-requisitos

1. Preparação do diretório de trabalho

2. Limpeza de cache e configuração local

3. Clone do spack-stack

4. Clone deste repositório e cópia das configurações

5. Verificação do compilers.yaml

6. Criação e ativação do ambiente

7. Concretização, instalação e meta-módulos

Uso dos módulos após a instalação

Indicadores de sucesso

Verificação pós-instalação

Testes funcionais

Teste NetCDF

Teste NetCDF-C++

Teste HDF5

Teste OpenMPI

Script automatizado

Observações importantes sobre a automação

Exemplo conceitual de uso

Ativação do ambiente após a instalação

Ambiente compartilhado para o grupo

Boas práticas de execução

Problemas comuns e soluções

1. Erro relacionado a flags ausente no compilers.yaml

2. Falha no spack stack setup-meta-modules

3. Bibliotecas dinâmicas não encontradas em tempo de execução

4. Problemas com OpenMPI e ambiente local

Informações que ainda precisam ser complementadas

Licença

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Relação entre `.env`, `site` e `template`

1. Bootstrap (`scripts/bootstrap/`)

2. Site (`configs/sites/<machine>/`)

3. Template (`configs/templates/`)

5. Verificação do `compilers.yaml`

1. Erro relacionado a `flags` ausente no `compilers.yaml`

2. Falha no `spack stack setup-meta-modules`

Packages