MdaMeX

Configure estudos geomecânicos, execute ajustes de modelos em um ambiente HPC e consulte os resultados diretamente no VS Code. A extensão reúne a edição de arquivos .mdamex, a validação de entradas, o acompanhamento de jobs Slurm e os leitores de resultados .mmout e .outh5.

Índice

• Requisitos e instalação
• Configurar o ambiente
• Mapear o workspace para o Linux
• Validar as entradas
• Criar e executar um estudo
• Acompanhar o estudo
• Consultar resultados
• Controlar o serviço e recuperar a conexão
• Refazer um ajuste
• Deletar um estudo
• Resolver problemas
• Autores e licença
• Desenvolvimento

Requisitos e instalação

• VS Code 1.75 ou superior, com uma pasta de trabalho confiável aberta.
• Acesso SSH ao ambiente HPC e permissão para utilizar os recursos Slurm do seu ambiente.
• Backend MdaMeX instalado no Linux, com suporte ao fluxo de estudos, e solver GeomecBR disponível no ambiente de execução.
• Pasta de modelos e resultados acessível pelo VS Code e pelo backend, com mapeamentos de caminhos configurados na extensão ou fornecidos pelo bootstrap.
• Arquivo de bootstrap corporativo: configuração dos perfis de conexão, executável e caminhos do ambiente.

A extensão é um cliente do backend; sua instalação não instala o backend, o solver ou o Slurm. Workspaces virtuais e o modo restrito do VS Code não são suportados.

Para instalar um pacote .vsix, abra a visualização Extensões, acesse o menu … e escolha Install from VSIX…. Selecione o pacote recebido.

Configurar o ambiente

1. Abra a pasta do projeto que contém studies/base/input.mdamex e studies/base/model/.
2. Abra a paleta de comandos (Ctrl+Shift+P; Cmd+Shift+P no macOS) e execute MdaMeX: Importar bootstrap corporativo.
3. Selecione o arquivo JSON de bootstrap fornecido para seu ambiente no seletor de arquivos.
4. Execute MdaMeX: Configurar credenciais SSH, se o perfil exigir senha ou passphrase. Perfis com agente SSH usam o agente configurado.
5. Execute MdaMeX: Testar conexões SSH para verificar o acesso ao orquestrador e ao Slurm.

As credenciais são armazenadas no armazenamento de segredos do VS Code. Elas não devem ser incluídas no arquivo científico .mdamex nem no bootstrap.

O usuário SSH é descoberto automaticamente com os.userInfo().username no sistema onde o host da extensão está executando (Windows local ou ambiente remoto, como Remote SSH/WSL). Para usar outro login, procure mdamex.connection.user nos Settings do usuário ou configure:

"mdamex.connection.user": "seu-login"

Esse setting tem prioridade sobre a descoberta automática e vale para o orquestrador e o Slurm em todos os perfis. Espaços nas extremidades são removidos e o login é convertido para minúsculas, como no vshpc. Vazio restaura a descoberta automática; o valor descoberto não é gravado nos settings nem no bootstrap.

O bootstrap e o ambiente corporativo não definem o usuário. Arquivos e caches antigos que contenham user continuam legíveis, mas o campo é descartado. Atualizações do bootstrap preservam a escolha dos settings. Se a descoberta falhar, a extensão pede que você configure mdamex.connection.user.

Depois de mudar o login, feche e reabra os painéis de estudos e jobs. Senhas e passphrases são associadas ao usuário, host e perfil; execute Configurar credenciais SSH para o novo login, quando necessário.

Os hosts também podem ser editados nos Settings, por nome de perfil:

"mdamex.connection.orchestratorHosts": {
  "geomec-hpc": "orchestrator.example.org"
},
"mdamex.connection.slurmHosts": {
  "geomec-hpc": "slurm.example.org"
}

Um perfil é uma entrada do bootstrap, como geomec-hpc; o workspace é o projeto aberto. Na importação ou atualização do bootstrap, os hosts preenchem apenas as entradas vazias nos Settings do usuário. Instalações com cache antigo recebem esse preenchimento ao carregar o ambiente. Valores já preenchidos são preservados, mesmo se uma revisão posterior do bootstrap mudar os hosts.

Você pode editar essas associações nas abas Usuário, Workspace ou Pasta dos Settings. Para cada perfil, pasta prevalece sobre workspace, que prevalece sobre usuário. Um projeto novo herda os padrões do usuário; alterações feitas apenas em outro workspace não são copiadas. Em workspaces com várias pastas, comandos de estudo usam a pasta selecionada; comandos gerais usam o arquivo ativo ou, na ausência dele, a única pasta aberta. Sem esse contexto, usam os settings do workspace e do usuário.

Uma entrada efetiva vazia ("geomec-hpc": "") usa o host do bootstrap já carregado. Remover uma entrada do workspace/pasta volta a herdar o valor do usuário. Após alterar hosts, feche e reabra os painéis e configure as credenciais do novo destino, quando necessário. Portas, autenticação e fingerprints continuam vindo do perfil.

O host do Slurm nos Settings controla as conexões da extensão para consultar jobs e testar SSH. As simulações e o diagnóstico nativo do backend usam execution.sshHost do arquivo .mdamex. O endereço WebSocket de um serviço já iniciado continua vindo do seu arquivo de descoberta service.json.

Para receber atualizações do bootstrap, configure mdamex.bootstrapSource com o caminho local ou a URL HTTPS fornecida pelo administrador. A opção mdamex.bootstrapAutoUpdate controla a atualização automática e vem habilitada. Use MdaMeX: Atualizar bootstrap corporativo para solicitar uma atualização manual. MdaMeX: Importar configuração corporativa (JSON) também aceita o formato legado de ambiente.

Por padrão, a extensão conecta diretamente ao orquestrador. Se o ambiente exigir proxy HTTP/PAC, procure MdaMeX: Orchestrator Connection Mode nas configurações do VS Code e selecione system. Também é possível configurar por projeto:

"mdamex.orchestrator.connectionMode": "system"

O modo system segue o proxy do VS Code e do ambiente. O padrão direct acessa o endpoint do orquestrador sem proxy HTTP/PAC, preservando autenticação e validação TLS. A escolha vale na próxima conexão; feche e reabra um painel já conectado. Essa opção não modifica o bootstrap, o SSH ou o proxy das outras conexões.

Mapear o workspace para o Linux

Execute MdaMeX: Configurar mapeamento workspace → Linux pela paleta ou pelo menu de contexto de uma pasta no Explorer. Selecione a pasta, o escopo de gravação (usuário, workspace ou pasta) e informe os caminhos correspondentes. O comando permite adicionar, editar, remover e restaurar a herança, com prévia antes de salvar. Não exige reimportar o bootstrap nem alterar os perfis SSH.

Na interface de Settings (Ctrl+,), procure mdamex.pathMappings. Na aba Usuário, use Adicionar Item para incluir a origem e o destino. Cada linha permite editar ou remover a associação, sem abrir o JSON nem usar o comando assistido. Também é possível configurar por workspace ou pasta.

O equivalente em settings.json é:

"mdamex.pathMappings": {
  "R:\\modelos": "/res/usuarios/usuario/modelos",
  "/mnt/modelos": "/res/usuarios/usuario/modelos"
}

A origem é um caminho absoluto visto pelo host da extensão: uma unidade Windows, um compartilhamento UNC ou uma montagem Linux. Em Remote SSH/WSL, use o caminho visto nesse ambiente. O destino é o caminho absoluto da mesma pasta no Linux do backend.

A cada conversão, a extensão:

1. Procura uma correspondência nos settings mdamex.pathMappings da pasta relevante.
2. Somente se nenhuma regra corresponder, procura nos pathMappings do bootstrap (ou ambiente corporativo legado).
3. Sem correspondência nas duas listas, mantém um caminho Unix absoluto; um caminho Windows gera erro com indicação do comando de configuração.

Dentro de cada lista, vence a origem mais específica, respeitando os limites de pasta. Uma regra dos settings vence mesmo quando o bootstrap contém uma origem mais específica. Por exemplo, uma regra pessoal para R:\modelos também prevalece sobre uma regra corporativa para R:\modelos\especial. Outro volume, sem regra pessoal correspondente, ainda pode ser resolvido pelo bootstrap.

O VS Code combina as associações dos settings por chave: para uma mesma origem, pasta tem prioridade sobre workspace, que tem prioridade sobre usuário. Origens diferentes são preservadas. Remover uma associação de um escopo permite que a regra herdada reapareça. Um objeto vazio não remove associações herdadas; sem nenhuma correspondência nos settings efetivos, usa-se o bootstrap. Restaurar herança remove a configuração no escopo escolhido. Atualizações do bootstrap não alteram os settings do usuário.

O formato anterior em lista continua legível pela extensão. Para convertê-lo ao objeto editável pela interface de Settings, edite e salve pelo comando assistido no mesmo escopo, ou substitua a lista no JSON pelo formato acima. O schema de Settings agora indica o formato de objeto.

A regra é compartilhada pela prévia, diagnóstico no backend e comandos de estudos, incluindo o caminho de origem de importação. A prévia mostra o caminho resolvido e se a regra veio dos settings, do bootstrap ou do uso direto de Unix. Essa tradução não verifica se as pastas representam os mesmos arquivos compartilhados e não copia arquivos. Use Testar configuração no backend para verificar os arquivos acessíveis.

Novas conversões leem os settings atuais. Feche e reabra estudos já abertos após mudar seus mapeamentos: destinos e operações pendentes preservam sua identidade, e uma inicialização pendente não pode ser repetida com outro destino.

Validar as entradas

Arquivos .mdamex usam JSON com comentários, com preenchimento automático e validação no editor. Campos desconhecidos, duplicados e vírgulas finais são recusados.

Clique com o botão direito no arquivo, no editor ou na aba e abra o menu MdaMeX:

Essas ações não iniciam simulações. A prévia não altera automaticamente a configuração original. O teste no backend exige uma instalação compatível, mas pode ser executado antes de iniciar o serviço do estudo.

Criar e executar um estudo

1. Execute MdaMeX: Novo estudo e informe um nome com letras minúsculas, números e hífens. O nome base é reservado.
2. Aguarde a criação do estudo e a abertura do painel.
3. O painel conecta ao serviço se ele estiver ativo. Se estiver parado, use Iniciar serviço.
4. Clique em Revisar e iniciar ajuste. Aguarde a validação das entradas e a preparação da configuração atual salva no estudo.
5. Confira o resumo apresentado, incluindo quantidade de simulações, recursos, parâmetros e destinos. Confirme em Iniciar ajuste para submeter as simulações.

Se fechar a revisão sem confirmar, o ajuste permanece preparado e nenhuma simulação começa. Você pode consultar as abas Entradas do estudo e Configuração do ajuste e voltar a Revisar e iniciar ajuste; a preparação será atualizada antes de apresentar o resumo novamente. Falhas na preparação interrompem o fluxo. Mudanças de estado ou configuração durante a revisão exigem uma nova revisão. Operações com resposta pendente devem ser recuperadas com Verificar operação pendente antes de continuar.

Criar o estudo, iniciar o serviço e preparar as entradas são etapas separadas do início das simulações. Para voltar a um estudo, execute MdaMeX: Abrir estudo. Quando o .mdamex selecionado pertence a um estudo existente, ele é aberto diretamente; nos demais casos, escolha um estudo no catálogo.

Cada estudo mantém sua configuração, trabalho, resultados e histórico. Arquivos HDF5 herdados da base podem ser compartilhados por links relativos para economizar espaço. Confira a coluna Armazenamento na aba Entradas do estudo: editar um arquivo compartilhado também altera a base. Mantenha a base disponível e inalterada; em montagens CIFS, os links relativos precisam funcionar na árvore do projeto. Estudos existentes podem manter cópias independentes.

Se a pasta candidata já contiver entradas próprias, elas prevalecem sobre as da base; um input.mdamex próprio precisa conter a configuração completa.

Acompanhar o estudo

O topo do painel mostra separadamente o estado do serviço e o estado do ajuste. O percentual indica as simulações validadas sobre o total previsto; passe o mouse sobre ele para ver as contagens. Quando a conexão é perdida, os dados exibidos representam o último registro recebido.

Use as abas para consultar entradas, configuração, ajustes e jobs, resultados e logs. Na lista de ajustes, Abrir seleciona a execução a acompanhar. Os hashes de arquivos e os IDs aparecem abreviados: clique para expandir ou use o botão de cópia para obter o valor completo, mesmo com o serviço desconectado.

Os diálogos de confirmação e seleção aparecem dentro da extensão. Cancelar ou Escape fecha o diálogo sem executar a ação. Quando solicitado um arquivo, informe seu caminho completo. Operações externas mostram progresso na barra de status do VS Code.

MdaMeX: Gerenciar jobs Slurm abre a consulta geral de jobs do usuário. Para interromper um ajuste MdaMeX, use Cancelar ajuste no painel do estudo e aguarde a confirmação do encerramento, pois o ajuste pode envolver várias submissões.

Consultar resultados

Na aba Resultados, clique em Consultar resultados e abra um dos arquivos completos listados para o ajuste selecionado.

Os arquivos precisam estar acessíveis na montagem usada pelo VS Code. O .mmout abre no leitor tabular da extensão; para .outh5, use MdaMeX: Abrir diagnóstico geomecânico no menu do arquivo. O backend pode remover resultados individuais depois da consolidação; consulte os arquivos disponibilizados pelo ajuste.

Controlar o serviço e recuperar a conexão

Se o painel perder a conexão, use Verificar serviço e Reconectar. Fechar o painel ou desconectar não cancela o ajuste. Se o serviço estiver parado, use Iniciar serviço.

Após uma interrupção, Iniciar e reconciliar inicia o serviço e recupera o acompanhamento dos jobs registrados. Se o serviço já estiver conectado e o painel solicitar reconciliação, use Reconciliar estudo. A reconciliação não retoma automaticamente o cálculo do ajuste nem inicia novas simulações.

Se aparecer uma operação com resultado pendente, use Verificar operação pendente antes de tentar outra ação. Isso permite recuperar o resultado da solicitação anterior.

Parar serviço encerra o serviço e mantém os resultados. A ação fica indisponível enquanto houver execução, cancelamento, reconciliação ou jobs pendentes. Cancele o ajuste e resolva as pendências antes de parar. Quando o backend não oferece essa função, o painel orienta sua atualização; reinicie o serviço após atualizar o backend.

Refazer um ajuste

Depois de concluir, cancelar ou encerrar um ajuste com falha, e sem jobs pendentes, clique em Refazer ajuste. Escolha como tratar a execução anterior:

• Novo estudo: copia as entradas para outro estudo e mantém o anterior. Inicie o serviço e prepare o ajuste no novo painel.
• Arquivar neste estudo: preserva trabalho, resultados e registros anteriores no histórico e prepara novamente as mesmas entradas.
• Descartar neste estudo: remove trabalho, resultados e registros anteriores após confirmação explícita e prepara novamente as entradas.

Para executar, confira a nova preparação e use Revisar e iniciar ajuste. Refazer no mesmo estudo depende de uma versão compatível do backend.

Deletar um estudo

Execute MdaMeX: Deletar estudo no menu do .mdamex ou na paleta de comandos. O estudo do arquivo selecionado é usado quando disponível; caso contrário, escolha-o no catálogo.

Confira o nome, a identidade e a pasta apresentados na confirmação. A exclusão remove permanentemente os arquivos, resultados e históricos daquele estudo. Feche o serviço e resolva os jobs pendentes antes de deletar. Essa operação exige suporte à exclusão de estudos no backend.

Após a confirmação do backend, o Explorador é atualizado. Ao fechar a mensagem de sucesso, a extensão abre e dá foco a studies/base/input.mdamex, preservando as alterações não salvas nos documentos abertos. Cancelamentos e falhas de exclusão não mudam o arquivo em foco. Se o caso base estiver inacessível, a extensão informa que a exclusão foi concluída e que não conseguiu abrir o arquivo.

Resolver problemas

Para consultar os registros da extensão, execute MdaMeX: Mostrar log ou abra Saída e selecione MdaMeX Log. Os logs do ajuste ficam na aba Logs do painel.

Autores e licença

Desenvolvido pela área de Reservatórios da Petrobras.

• Gabriel de Oliveira da Silva
• Gabriel Serrão Seabra
• Rogério Ferreira da Cunha

Publisher: ESMDA Geomechanic (esmda-geo). ID da extensão: esmda-geo.mdamex-ext. Licença MIT; consulte os arquivos LICENSE e THIRD_PARTY.md distribuídos com a extensão. O histórico de versões está em CHANGELOG.md e na aba de alterações da extensão.

Desenvolvimento

O repositório do projeto tem acesso restrito aos usuários autorizados. As instruções de instalação das dependências, build, testes e contratos estão em mdamex-ext/DEVELOPMENT.md no código-fonte. No diretório da extensão, use npm run build:all para compilar, npm test para os testes locais e npm run package para gerar o VSIX. O empacotamento executa o build e não publica no Marketplace.