U1.L1 — Lab 0: ambiente e tensores numéricos

Sessão U1.L1 · data: ver calendar-map

Esta é a primeira sessão de laboratório do curso. Nas sessões de laboratório o notebook é a aula: não há um PDF de notas separado. Esta página reúne o que precisa ser feito antes da sessão, o roteiro de instalação do ambiente e o mapa do que o notebook percorre.

A sessão tem três objetivos.

Fundar o ambiente computacional do semestre. O ambiente env-mae369 criado hoje é o mesmo usado em todos os laboratórios e em todos os itens numéricos das listas, até o mini-projeto da Unidade 9.
Tornar executável a álgebra tensorial de U1.T1 e U1.T2. A função np.einsum recebe uma string de índices como argumento; essa string é a notação indicial escrita de maneira que o computador a execute.
Instalar a regra de verificação do curso, enunciada na seção A regra de verificação do curso.

Antes da sessão

O único pré-requisito é o gerenciador miniforge instalado. O roteiro de instalação está no apêndice das notas de U1.T1.

Se a instalação do miniforge falhou, traga a mensagem de erro: há tempo reservado no início da sessão para resolver esses casos. Não tente criar o ambiente antes da sessão sem o miniforge instalado.

O ambiente do curso: `env-mae369`

O arquivo environment.yml descreve o ambiente com todas as versões fixadas. Salve-o em uma pasta de trabalho da disciplina antes de começar.

O ambiente inclui fenics-dolfinx e gmsh, que só serão usados na Unidade 9. A instalação é feita uma única vez, no início do semestre; por isso esses dois pacotes entram desde já.

Abra o Miniforge Prompt pelo menu Iniciar. Não use o Prompt de Comando comum nem o PowerShell.
Vá até a pasta em que o arquivo foi salvo, por exemplo:
```
cd %USERPROFILE%\Documents\MAE369
```
Crie o ambiente:
```
conda env create -f environment.yml
```
A criação baixa cerca de 1 GB e leva de 5 a 15 minutos.
Ative o ambiente:
```
conda activate env-mae369
```

Abra um terminal novo, depois de instalar o miniforge. O prompt deve começar com (base); se não começar, feche o terminal e abra outro.
Vá até a pasta em que o arquivo foi salvo, por exemplo:
```
cd ~/MAE369
```
Crie o ambiente:
```
conda env create -f environment.yml
```
A criação baixa cerca de 1 GB e leva de 5 a 15 minutos.
Ative o ambiente:
```
conda activate env-mae369
```

O miniforge instala também o comando mamba, que resolve as dependências mais depressa e aceita exatamente os mesmos argumentos. Onde estiver escrito conda env create, pode-se escrever mamba env create. Os dois produzem o mesmo ambiente.

Verificação

Com o ambiente ativo, abra o notebook:

jupyter lab

A primeira célula do notebook imprime as versões instaladas e desenha uma figura. Ela é o Checkpoint 0: se executa sem erro, o ambiente está pronto.

Problemas frequentes

Sintoma	Causa provável	O que fazer
`conda: command not found`	O terminal foi aberto antes da instalação do miniforge	Feche o terminal e abra outro
A criação do ambiente falha em meio ao download, no Windows	A pasta do usuário está sincronizada pelo OneDrive	Reinstale o miniforge em `C:\miniforge3`
`conda activate` não muda o prompt	O `conda` não foi inicializado para o interpretador de comandos em uso	Execute `conda init` e abra um terminal novo
A criação demora mais de 30 minutos	Resolução de dependências lenta	Interrompa e repita com `mamba env create -f environment.yml`

Se nenhuma das linhas acima resolver, registre a mensagem completa de erro e traga-a para a sessão.

O notebook `nb-tensores`

O notebook do aluno é lab-u1l1.ipynb. A versão com as soluções é publicada nesta mesma página depois da sessão.

O notebook tem três tipos de célula: as dadas, que já vêm completas; as de TODO, numeradas por bloco, que são o trabalho da sessão; e as de checkpoint, que terminam em assert e dizem se é seguro seguir adiante.

flowchart TD
  B0["<b>Bloco 0</b><br/>o ambiente<br/><i>Checkpoint 0</i>"]
  B1["<b>Bloco 1</b><br/>a regra de verificação"]
  B2["<b>Bloco 2</b><br/>einsum e a identidade ε–δ<br/><i>Checkpoints 1 e 2</i>"]
  B3["<b>Bloco 3</b><br/>autovalores e direções principais<br/><i>Checkpoints 3 e 4</i>"]
  B4["<b>Bloco 4</b><br/>mudança de base<br/><i>Checkpoint 5</i>"]
  B5["<b>Última célula</b>"]
  B0 --> B1 --> B2 --> B3 --> B4 --> B5

Bloco	O que se faz	O que se usa de U1
0	Cria o ambiente e confere que ele funciona	—
1	Fixa a regra de verificação do curso, em um exemplo de três linhas	—
2	Escreve cinco contrações com `einsum` sobre tensores não simétricos e confere cada uma contra a forma matricial; constrói \(\varepsilon_{ijk}\) e verifica a identidade \(\varepsilon\)–\(\delta\) nas 81 componentes	U1.T1: convenção de soma, \(\delta_{ij}\), \(\varepsilon_{ijk}\), identidade \(\varepsilon\)–\(\delta\)
3	Calcula \(I_1\), \(I_2\), \(I_3\) na forma indicial, monta a equação característica e confere as raízes contra `np.linalg.eigh`; verifica a ortonormalidade das direções principais	U1.T2: invariantes e equação característica (Resultado 1.5)
4	Sorteia uma rotação \(\mathbf Q\), escreve \(T'_{ij} = Q_{mi}Q_{nj}T_{mn}\) das duas formas e recalcula os três invariantes	U1.T1: lei de transformação
5	Célula dada, executada por todos	—

O que cada bloco mostra

As quatro animações abaixo acompanham os blocos 2, 3 e 4. Elas não substituem o notebook: cada uma mostra, em movimento, o que a célula correspondente calcula em silêncio.

Bloco 2 — o índice somado

O tensor e o vetor são os mesmos do TODO 2.1. O índice \(j\) percorre 1, 2 e 3, e as três parcelas se acumulam na componente do resultado: é essa soma que a string 'ij,j->i' abrevia.

Bloco 2 — a identidade \(\varepsilon\)–\(\delta\) nas 81 componentes

Cada grade tem uma linha por par \((j,k)\) e uma coluna por par \((m,n)\): são \(3^4 = 81\) igualdades simultâneas. As duas grades se preenchem em paralelo e resultam na mesma imagem — que é o que o Checkpoint 2 verifica.

Bloco 3 — onde o determinante se anula

Enquanto \(\lambda\) percorre o eixo, as três entradas diagonais de \(\mathbf T - \lambda\mathbf I\) mudam e o determinante é redesenhado. Uma raiz não é um ponto marcado no gráfico: é o valor de \(\lambda\) em que a matriz deixa de ser invertível. Os três valores obtidos assim são os mesmos que np.linalg.eigh devolve — o cruzamento dos dois caminhos que o Checkpoint 3 verifica.

Bloco 4 — o que não muda quando a base muda

Esta animação é a mesma das notas de U1.T2. Ela mostra a afirmação que o bloco 4 põe à prova: sob a rotação da base as nove componentes correm, e \(I_1\), \(I_2\) e \(I_3\) não se movem.

A regra de verificação do curso

Todo objeto numérico central deste curso é escrito uma vez do zero, a partir da definição, e conferido contra uma implementação independente do mesmo objeto. As duas são comparadas com np.allclose, com a tolerância declarada na própria comparação.

Figura 1: O procedimento de verificação, fundado nesta sessão e repetido em U6.L1 e U9.L1.

Duas razões sustentam a regra. A primeira é que transcrever a definição é o que obriga a entendê-la; uma chamada de biblioteca não obriga a nada. A segunda é que a discordância entre os dois caminhos localiza o erro no tempo: ela diz que um dos dois está errado, e diz isso antes que o resultado contamine o resto do notebook.

O que a regra não faz: ela não demonstra nada. A verificação numérica confere um caso; a garantia de que um resultado vale continua vindo da demonstração. No bloco 2, por exemplo, a identidade \(\varepsilon\)–\(\delta\) é conferida em todas as 81 combinações de índices, e ainda assim quem estabelece a identidade é a demonstração feita em U1.T1.

O que cada checkpoint verifica

Checkpoint	Bloco	O que precisa valer
0	0	As bibliotecas do curso importam e uma figura é desenhada
1	2	As cinco contrações concordam nas formas indicial e matricial
2	2	\(\varepsilon_{ijk}\varepsilon_{imn} = \delta_{jm}\delta_{kn} - \delta_{jn}\delta_{km}\) nas 81 componentes, com desvio exatamente nulo
3	3	Os invariantes concordam nas duas formas, e as raízes da equação característica concordam com `np.linalg.eigh`
4	3	As direções principais são ortonormais e satisfazem \(\mathbf T\mathbf n = \lambda\mathbf n\)
5	4	As nove componentes mudam sob a mudança de base; os três invariantes não

As tolerâncias de cada assert são declaradas na própria célula, e o texto que a antecede explica de onde veio o valor. Nenhuma delas é arbitrária: uma tolerância frouxa demais aprova um erro de implementação, e uma tolerância estreita demais reprova aritmética correta.

Reprodutibilidade

O notebook define uma única semente, no topo, e dela derivam os geradores de cada bloco:

SEED = 20260824
rng = np.random.default_rng(SEED)
rng_exemplo, rng_rotacao = rng.spawn(2)

Duas exigências valem para toda entrega numérica desta disciplina, e nascem aqui: a semente é fixa e está escrita no arquivo, e toda comparação numérica declara sua tolerância. Um resultado que muda a cada execução não pode ser conferido por quem corrige.

Ligação com a Lista 1

O bloco 4 é a versão numérica do item (e) de PS1.4: a lista pede a demonstração geral de que \(I_1\), \(I_2\) e \(I_3\) não dependem da base, e o item final pede a mesma verificação numérica feita aqui, com outra semente.

O bloco 2 acompanha PS1.1 como estudo recomendado, não avaliado: reproduzir a verificação da identidade \(\varepsilon\)–\(\delta\) ajuda a conferir as manipulações do item (a). O item avaliado continua sendo a demonstração no papel.

Depois da sessão

Ao final você tem três coisas: um ambiente que dura o semestre, a álgebra tensorial de U1 executando com verificação cruzada, e o notebook completo. Guarde o notebook executado — ele será reaberto mais adiante no curso.

A próxima sessão (U2.T1) inicia a cinemática.