# Glosario, convenciones y protocolo de entrega — TEL-420 Sistemas Paralelos

Documento de gobernanza del repositorio. Deriva de `programa-docente-TEL420-V2.docx`
apartados 20 (Ruta Formativa), 22 (Recursos) y 23 (Alianzas), y de la Guia Oficial del
Proyecto Final Integrador.

---

## 1. Fuente de verdad y reglas de gobernanza

1. **Fuente unica:** `00-marco/programa-docente-TEL420-V2.docx`. Este archivo **no se
   modifica**. Si la Carrera publica una version V3, se agrega como archivo nuevo y se
   regenera la matriz de trazabilidad.
2. **Todo artefacto se declara:** cada unidad de aprendizaje, guia, rubrica y evaluacion
   debe existir en `matriz-trazabilidad.md` y `.csv` antes de entregarse al estudiante.
3. **Ningun contenido sin fuente:** los contenidos siguen la nomenclatura del programa
   (numero EC, numero de contenido, semana). No se agregan temas que no esten en el
   apartado 20.
4. **Materiales existentes son semilla, no canon:** los 14 archivos de `99-legacy/` se
   reutilizan, se normalizan y se migran. No se editan en su ubicacion original.
5. **Idioma:** castellano en todo el material. Los terminos tecnicos en ingles se conservan
   entre parentesis en su primera aparicion por section (por ejemplo "Memoria
   compartida (Shared Memory)").

---

## 2. Nomenclatura de archivos

| Elemento | Patron | Ejemplo |
|---|---|---|
| Contenido de modulo | `M<n>-<slug>.md` | `M1-fundamentos.md` |
| Guia de practica | `P<ec><n>-<slug>.odt\|md` | `P5b-rag-dockerizado-ocr.odt` |
| Rubrica | `rubrica-<instrumento>.md` | `rubrica-codigo-openmp.md` |
| Banco de preguntas | `<tipo>-<modulo>.json` | `sumativa-M3.json` |
| Evaluacion generada | `<NN>_<modulo>_<tipo>.html` | `06_M3_sumativo.html` |
| Rutas de codigo | `scripts/`, `src/`, `benchmark/` | `benchmark/run.sh` |

**Reglas:**
- Solo minusculas y guiones en los nombres; nada de espacios ni acentos.
- Numero de modulo con prefijo `M`, guia de practica con prefijo `P`, rubrica siempre con
  el prefijo `rubrica-`.
- Numeracion de dos digitos en las evaluaciones generadas para mantener el orden.

---

## 3. Formatos de entrega permitidos

| Tipo de entrega | Formato | Naming del archivo entregado por el estudiante |
|---|---|---|
| Unidades de aprendizaje | ODT, DOCX, PDF, HTML | lo que el docente indique en clase |
| Questionarios (evaluaciones) | **HTML autocontenido** | `evaluacion_<ApellidoNombre>.pdf` (el reporte impreso) |
| Informes de laboratorio | PDF | `informe_<ApellidoNombre>_<Modulo>.pdf` |
| Codigo fuente | Repositorio Git publico | `github.com/<usuario>/<proyecto>` |
| Rebuttes / datos | CSV, XLSX, PNG, SVG | dentro del repositorio, carpeta `data/` |

**Regla general:** el unico formato obligatorio para cualquier entrega es **PDF**. El
repositorio Git es obligatorio para todo entregable que contenga codigo.

---

## 4. Protocolo de autenticidad de evidencias

Este protocolo **unifica** lo que hoy cada guia aplica de forma distinta (marca visible en
capturas, minimo de commits, repositorio publico). Cualquier entrega debe cumplir **al
menos** los cuatro puntos.

### 4.1 Identificacion del estudiante
Todo archivo de codigo fuente lleva en la cabecera el identificador:

```c
/* Sistemas Paralelos - TEL420
 * Estudiante: NOMBRE COMPLETO
 * RU / CI: XXXXXXXX
 * Fecha: AAAA-MM-DD
 * Practica: P3 - Comunicaciones colectivas
 */
```

```python
# Sistemas Paralelos - TEL420
# Estudiante: NOMBRE COMPLETO
# RU / CI: XXXXXXXX
# Practica: P5b - Ingesta concurrente RAG
```

### 4.2 Marca de agua en evidencias graficas
Toda captura de pantalla o fotografia debe incluir **nombre completo y RU/CI** visibles de
forma permanente, integrados mediante uno de estos medios:

- `echo "Practica realizada por: NOMBRE - RU" > /tmp/marca && cat /tmp/marca` antes de capturar;
- un comentario visible en el terminal, en el editor de codigo o en la linea de comandos;
- el nombre del usuario del sistema operativo visible en la barra de tareas o en la terminal;
- una nota o papel manuscrito al lado del dispositivo fotografiado;
- una etiqueta añadida en el grafico generado, con el nombre en la leyenda.

Un post-proceso con un editor de imagen **no es admisible**: el nombre debe aparecer de
forma natural en el momento de la captura.

### 4.3 Historial de version verifiable
- Repositorio Git publico, con **al menos 3 commits** que no sean triviales.
- Mensajes de commit en castellano bajo la convencion de *Conventional Commits*:

| Prefijo | Uso | Ejemplo |
|---|---|---|
| `feat` | nueva funcionalidad | `feat(backend): agregar modelo de datos en schema.prisma` |
| `fix` | correccion de error | `fix(docker): corregir puerto de conexion a postgres` |
| `docs` | documentacion | `docs(readme): agregar instrucciones de ejecucion` |
| `refactor` | reestructuracion sin cambio de comportamiento | `refactor(mpi): separar comunicacion de la logica de dominio` |
| `perf` | mejora de rendimiento | `perf(openmp): cambiar schedule a guided para equilibrar la carga` |
| `chore` | mantenimiento o configuracion | `chore(docker): actualizar imagen base a ubuntu 22.04` |
| `test` | pruebas | `test(benchmark): agregar caso N grande` |

- Historial **sin `force push`**: los commits intermedios deben ser visibles.
- Cada commit debe corresponder a un hito real de la practica, no a un volcado masivo.

### 4.4 Repositorio reproducible
- El evaluador debe poder **clonar y ejecutar con un solo comando** y obtener compilacion,
  ejecucion y metricas. Comandos de referencia:
  `./benchmark.sh`, `docker compose up --build`, `make run`.
- `README.md` completo: requisitos, instalacion, ejecucion, estructura, resultados esperados.
- Archivo `.env.example` versionado; el `.env` real **nunca** se sube al repositorio.
  Si se Versiona, las credenciales deben ser ficticias o de prueba.
- Sin credenciales reales (claves API, tokens, contrasenas) en el historial de Git.
  Una clave filtrada se considera **falta deontica grave**, no un error tecnico subsanable.

---

## 5. Criterios de authorship de las capturas y reports de evaluacion

### 5.1 Evaluaciones HTML
- El archivo HTML es **autocontenido**: un solo archivo, sin dependencias externas, que
  funcione sin conexion a internet en cualquier navegador moderno.
- Al finalizar, el estudiante descarga el **reporte en PDF** y lo entrega.
- El reporte incluye la **huella SHA-256** de integridad. Esta huella sirve para detectar
  copias entre companeros; **no es un mecanismo criptografico de seguridad**, porque la
  clave de la sal es visible en el codigo fuente del examen.
- Cada examen declara su identificador, modulo, duracion, numero de preguntas y nota minima.
- Los expirados se autoentran y el estudiante no puede responder al cambiar de pestana.
  La perdida de foco reinicia el intento y queda registrado en el reporte.

### 5.2 Simbologia para la destruccion de la copia
Se usara una **tecla de salida** visible en la pantalla (por ejemplo `CTRL + ALT + S` en
una aplicacion de escritorio, o el equivalente en linea) que:
- reinicia el examen con un banco de preguntas reordenado;
- borra las respuestas previas;
- reinicia el temporizador;
- deja constancia del incidente en el reporte final.

Esta medida disuade la copia pero **no la elimina**: el docente debe combinar las
herramientas tecnicas con la defensa oral y la revision del codigo del estudiante.

---

## 6. Glosario tecnico de la asignatura

Terminos que deben aparecer siempre con su equivalencia en ingles en la primera mencion.

| Castellano | Ingles | Simbolo /Notacion |
|---|---|---|
| Ganancia de velocidad | Speedup | `S_p = T_1 / T_p` |
| Eficiencia | Efficiency | `E_p = S_p / p` |
| Escalabilidad fuerte | Strong Scaling | tamano de problema fijo |
| Escalabilidad debil | Weak Scaling | carga por procesador constante |
| Ley de Amdahl | Amdahl's Law | `S_p = 1 / (s + (1-s)/p)` |
| Ley de Gustafson-Barsis | Gustafson-Barsis Law | `S_p = p - s'(p-1)` |
| Comunicacion bloqueante | Blocking Send/Recv | `MPI_Send` / `MPI_Recv` |
| Comunicacion no bloqueante | Non-blocking Send/Recv | `MPI_Isend` / `MPI_Irecv` |
| Falsa comparticion | False Sharing | cacheline de 64 bytes |
| Seccion critica | Critical Section | `#pragma omp critical` |
| Reduccion | Reduction | `#pragma omp reduction(+:x)` |
| Cerrojo / exclusion mutua | Mutex | `omp_lock_t` |
| Grilla | Grid | `gridDim` |
| Bloque | Block / Thread Block | `blockDim`, `blockIdx` |
| Hilo en GPU | Warp | 32 hilos (NVIDIA) |
| Unico hilo, multiples datos | Single Instruction Multiple Data | SIMD |
| Acceso no uniforme a memoria | Non-Uniform Memory Access | NUMA |
| Interconexion de acceso directo a memoria remota | Remote Direct Memory Access | RDMA |

> Nota: los terminos del glosario deben usarse de forma uniforme en M2, M3 y M4
> para evitar errores ortograficos y terminologicos.

---

## 7. Formato de citacion bibliografica

Se usa el estilo **APA 7**, coherente con las referencias del apartado 24 del programa.

**Artículo de revista:**
> Quinn, M. J. (2004). Parallel programming in C with MPI and OpenMP. McGraw-Hill.

**Libro:**
> Pacheco, P. (2021). An introduction to parallel programming (2nd ed.). Morgan Kaufmann.

**Documentación técnica en línea** (con fecha de consulta):
> NVIDIA. (2023). CUDA C++ programming guide. Documentación en línea.
> https://docs.nvidia.com/cuda/cuda-c-programming-guide/

**Especificación de estándar:**
> Message Passing Interface Forum. (2021). MPI: a message-passing interface standard
> (Version 3.1). https://www.mpi-forum.org/docs/mpi-3.1/mpi31-report.pdf

**Reglas adicionales:**
- Toda guia de laboratorio debe incluir al menos **3 referencias** de la bibliografia del
  programa o de documentacion oficial vigente.
- Las citas en el codigo fuente usan el formato de comentario del punto 4.1.
- Los datasets usados en las practicas se citan con su URL y su licencia de uso.

---

## 8. Recursos y platforms de la asignatura

Plataformas oficiales de la materia:

| Plataforma | Uso | Enlace de referencia |
|---|---|---|
| **Moodle institucional** | Gestion del curso, publication de materiales, envio de tareas | definido por la carrera |
| **GitHub** | Repositorios de codigo y entregas | `github.com` |
| **Repositorio del docente** | Codigo de referencia y plantillas | `github.com/eliascassaluajms` |

Repositorios de referencia ya publicados por el docente:

| Repositorio | Proyecto | Utilidad en la asignatura |
|---|---|---|
| `eliascassaluajms/syslab2.0` | Sistema de gestion integral de laboratorios (Node/Express + React/Vite + PostgreSQL/Prisma) | P5: despliegue y orquestacion de contenedores |
| `eliascassaluajms/lexbancario-ai` | Sistema RAG de normativa bancaria (FastAPI + Streamlit + Supabase + Gemini) | P5b: ingesta concurrente con OCR y batching |

Infraestructura de laboratorio (segun la Guia Oficial del Proyecto Integrador):
estaciones **Dell OptiPlex Power Plus 7010**, Intel Core i7, 32 GB RAM, red Gigabit Ethernet,
sistema base Ubuntu Linux o WSL2.

> **Limitacion relevante:** los equipos de laboratoryo son portatiles y **no dispone de
> GPU NVIDIA dedicada**. Por eso el modulo M4 (CUDA) incluye un **plan B obligatorio**
> basado en simulacion de la arquitectura CUDA o en comparacion CPU (OpenMP) frente a
> ejecucion acelerada, de modo que todos los estudiantes puedan aprobar el modulo.

---

## 9. Alianzas estrategicas (apartado 23 del programa)

| Alianza | Tipo de aporte | Uso en la asignatura |
|---|---|---|
| Asociacion de Empresas de Tecnologia de Tarija (AETI) | charlas tecnicas de profesionales | M5: casos reales de computacion paralela en la industria regional |
| Laboratorio de Computacion Cientifica de la UAJMS | acceso a infraestructura compartida | M3 y M4: nodos adicionales y perfiles de rendimiento |
| Empresas locales de telecomunicaciones o mineria | casos de estudio | M5: problema real regional para el Proyecto Integrador |

Estas alianzas son de gestion; su formalizacion es responsabilidad de la carrera.

---

## 10. Checklist de publicacion de un artefacto

Antes de entregar cualquier material al grupo de estudiantes, verificar:

- [ ] Existe su fila en `matriz-trazabilidad.md` y `.csv`.
- [ ] El nombre del archivo cumple la nomenclatura del punto 2.
- [ ] Los contenidos corresponden al apartado 20 del programa (sin temas agregados).
- [ ] Las semanas citadas coinciden con el calendario vigente.
- [ ] Los terminos tecnicos aparecen con su equivalencia en ingles (glosario, punto 6).
- [ ] La bibliografia esta en formato APA 7 e incluye al menos 3 fuentes.
- [ ] Las figuras son vectoriales o tienen resolucion suficiente para impresion.
- [ ] Las actividades practicas tienen evidencia requerida y criterio de evaluacion explicito.
- [ ] Si es un HTML de evaluacion: funciona sin conexion, es autocontenido y el banco
      tiene al menos 22 preguntas si se muestrea 20.
- [ ] Si es una rubrica: los criterios se derivan de los instrumentos del apartado 18.2.

---

## 11. Control de versiones de este documento

*Derivado de `programa-docente-TEL420-V2.docx` (apartados 20, 22, 23 y 24) y de la Guia
Oficial del Proyecto Final Integrador (ABP-FBC).*
*Si el programa docente se actualiza, revisar especialmente el punto 8 (recursos) y el
punto 9 (alianzas).*