# 격자, 계산 비용과 복구 [색인](/llms.txt) · [핵심 개념](/docs/agents/concepts.md) ## 실제 계산 격자 `domain.dx`, `domain.dy`는 입력 격자입니다. `visualSetting.resolution`에 따라 계산 간격이 달라집니다. | 해상도 저장값 | UI 의미 | 실제 X 간격 dxn | 실제 Y 간격 dyn | 같은 도메인의 XY 열 수 배율 | | --- | --- | --- | --- | --- | | 1 | 낮음 | dx | dy | 1 | | 2 | 보통 | dx / 2 | dy / 2 | 4 | | 3 | 높음 | dx / 4 | dy / 4 | 16 | 문서 코덱과 프로젝트 격자 도우미의 기본 해상도는 2입니다. 따라서 입력 dx 5 nm가 실제 2.5 nm가 되는 것은 기본 보통 해상도의 경우입니다. 항상 절반이라는 규칙은 아닙니다. 불완전한 내부 스냅샷을 직접 복원하면 다른 초기값이 개입할 수 있으므로 실제 정규화된 격자를 확인하세요. `NX ≈ LX / dxn`, `NY ≈ LY / dyn`, `Ncols = NX × NY`입니다. X/Y 크기와 간격의 나눗셈이 유효해야 하며 엔진은 정규화된 값을 사용합니다. 프로젝트 크기·격자 설정창은 입력을 바꿀 때 기본 격자와 실제 계산 격자, XY 열 개수, 구조 격자와 작업 격자의 추정 용량을 갱신합니다. 표시 단위와 무관하게 계산은 정규화된 nm 값을 사용합니다. 유효하지 않은 입력은 추정 불가로 표시합니다. 새 프로젝트 생성창에서도 크기·표시 단위를 바꿀 때 X/Y 크기 아래 한 줄로 실제 계산 간격과 XY 지점(열) 수를 미리 확인할 수 있습니다. 메모리 한도에 가까울 때만 같은 자리에 크기 축소·격자 간격 확대 안내가 추가됩니다. ## 예상 메모리의 범위 현재 앱의 구조 메모리는 블록별 구간 용량과 공유 상태에 따라 달라집니다. 다음 식은 모든 열에 같은 `Lmax`를 할당하고 공유하지 않는 기존 dense 저장 방식의 용량 추정입니다. 현재 블록 구조의 실소유량 측정으로 해석하지 마세요. ```text uniform-capacity snapshot bytes ≈ Ncols × (8 × Lmax + 2) ``` `Lmax`는 열당 할당된 구간 수 용량입니다. 각 구간의 재료/기원 토큰과 높이는 각각 Uint32, 열 길이는 Uint16입니다. 다음 표는 **Lmax=32·균일 용량·비공유 스냅샷 한 개**의 예시이며 전체 탭 메모리나 안전한 최대 크기가 아닙니다. | 도메인 | 실제 XY 간격 | XY 열 수 | 스냅샷 한 개 추정 | | --- | --- | --- | --- | | 200 × 100 nm | 2 × 2 nm | 5,000 | 약 1.23 MiB | | 2,000 × 2,000 nm | 5 × 5 nm | 160,000 | 약 39.37 MiB | | 4,500 × 2,200 nm | 2.5 × 2.5 nm | 1,584,000 | 약 389.74 MiB | 현재 구조의 실소유량은 블록별 용량과 공유 상태에 따라 달라집니다. 여기에 캐시, 계산 임시 배열, provenance, 전달 중 복사본, 3D 메시, GPU 버퍼, JS 객체가 추가됩니다. 압축된 저장 파일이 작아도 복원·계산·렌더링에는 큰 메모리가 필요할 수 있습니다. `status().engineBufferBytes`는 엔진 소유 버퍼와 캐시만의 관측이고 `performance.memory`는 현재 JS 문맥의 힌트이므로, 파일 크기·앞의 추정식·일부 메모리 관측만으로 실행 가능 여부를 단정하거나 미측정 값을 0으로 바꾸지 마세요. 설정창의 “작업 격자”는 구조 스냅샷 한 개 추정의 3배인 작업량 휴리스틱입니다. 전체 최대 사용량 측정이나 안전한 실행 보장이 아닙니다. 보고된 현재 JS 힙 한도가 있고 사용량 또는 작업 격자 추정이 그 한도의 80% 이상이면 주의를 표시합니다. Worker·GPU·탭 전체 메모리는 이 비교만으로 알 수 없습니다. 같은 메모리 주의는 초기 격자 할당 전과 사용자가 요청한 계산의 공정 실행 전에도 표시됩니다. 계산을 차단하거나 해상도를 자동으로 바꾸지 않습니다. 힙 한도를 보고하지 않는 브라우저에서는 알 수 없는 상태를 유지하며, 주의가 없다는 것이 메모리 여유를 보장하지는 않습니다. 계산 시간은 열 수뿐 아니라 노출면, 측면 확산 거리, 반복 수, 캐시 적중, 공정 종류와 장치에 따라 달라집니다. 한 사용자의 “단계당 15초”나 “4 GB에서 충돌”을 보편적인 한도로 사용하지 마세요. 작은 도메인과 짧은 공정 접두부에서 먼저 확인하고, 좁은 형상이 최소 여러 계산 셀에 걸쳐 표현되는지 점검한 뒤 확대하세요. ## 캐시, 복구본, 저장본 ### 메모리 실패와 재시도 계산 중 자원 할당에 실패하거나 Worker 응답을 받는 JavaScript 처리 안에서 버퍼 할당 오류가 발생하면, 실패한 엔진을 폐기하고 대기 중인 요청을 실패로 종료합니다. 같은 입력의 자동 부수 요청으로 즉시 재계산하지 않습니다. 남아 있는 마지막 화면은 실패한 목표 단계의 완성 결과가 아닙니다. 재시도 전 오류가 발생한 작업, 현재 계산 상태, 중복 작업·탭, 실제 저장본과 체크포인트를 확인하세요. 사용자가 요구한 해상도·도메인·공정은 유지합니다. 이를 바꿔야 하는 경우 결과에 미치는 영향을 설명하고 동의를 받은 뒤 변경하세요. 저장 한도 초과와 [본딩 원본 준비 실패](/docs/agents/tasks/bonding.md)는 메모리 부족과 구분해 해당 안내를 따르세요. 이 보호는 처리 가능한 예외의 범위입니다. 브라우저나 운영체제가 탭을 강제 종료하거나 JavaScript 이벤트 처리에 도달하기 전에 실패하는 경우까지 복구를 보장하지 않습니다. 저장본과 실제로 보존된 체크포인트를 확인해야 합니다. 현재 구조·캐시 전송에는 Transferable을 사용하는 경로가 이미 있습니다. 계산 원본을 보존하는 전송 복사본과 화면의 이전 결과가 함께 존재할 수 있어 메모리 사용량이 0이 되는 것은 아닙니다. 수치 단면 조회는 전체 구조 조회와 다른 경로이며, 숫자 단면만 필요하면 `getCrossSection`을 사용하세요. 대형 프로젝트는 같은 워크스페이스를 재사용하고 복원·계산·추가 분석을 순서대로 실행하세요. 진행 중 중복 요청, 탭 복제, 반복 새로고침을 피합니다. 페이지 이동만으로 이전 계산 메모리가 즉시 해제된다고 가정하지 마세요. 탭 종료·새로고침을 복구 수단으로 선택할 때는 저장 및 미저장 작업을 먼저 확인하고, 사용자 작업을 잃을 수 있는 종료에는 동의가 필요합니다. 저장한 적 없는 프로젝트(새 프로젝트, `setFlow`·Flow JSON·Flow 링크로 연 프로젝트)를 편집한 상태라면 브라우저가 확인 창을 띄우고 답할 때까지 페이지가 멈추므로 사용자에게 답을 맡기세요. 새로고침 뒤 "저장하지 않은 프로젝트입니다" 안내에 "복구해서 열기"가 있으면 이 브라우저에 남은 마지막 편집 상태를 저장 전 새 프로젝트(새 주소)로 엽니다. ### 보존 범위 실행 중 캐시는 메모리 예산에 따라 제한됩니다. 현재 코드에는 문서에 맞는 선택 단계 캐시를 로컬 복구본에 넣는 경로와 저장 프로젝트의 계산 체크포인트 경로가 이미 있습니다. 따라서 “새로 열면 모든 캐시가 반드시 사라진다”도, “모든 단계가 자동으로 영구 보존된다”도 정확하지 않습니다. - 복구 캐시는 선택 단계, 공정 접두부, 마스크, 재료 의미, 도메인, 엔진 버전 등이 맞아야 재사용합니다. - 캐시가 너무 크거나 저장소 할당량이 부족하면 문서만 보존하고 계산을 다시 해야 할 수 있습니다. - 브라우저 프로필을 바꾸거나 사이트 데이터를 지우면 로컬 복구본을 찾을 수 없습니다. - 예전 캐시를 억지로 연결하지 마세요. 입력이 달라진 캐시 재사용은 잘못된 구조를 보여줄 수 있습니다. - 큰 작업 전·중간에 문서를 저장하고, 복구/체크포인트 상태를 확인하세요. 캐시가 있다는 이유만으로 저장 성공을 보고하지 마세요. 저장 프로젝트를 다시 열 때는 [복원 후 확인 순서](/docs/agents/api.md#저장본을-다시-열-때)를 따르세요. 유효한 선택 단계 결과가 복원됐으면 바로 전체 재계산을 요청하지 않습니다. 현재 저장 경로의 제한은 다음처럼 서로 다른 범위입니다. 한 수치를 다른 경로의 메모리 예산으로 바꾸어 해석하지 마세요. | 경로 | 현재 제한과 의미 | | --- | --- | | 로컬 문서 복구 | 편집 후 10초 또는 10회 변경에 맞춰 쓰기. 편집 세션 복구본의 보존 기준은 10일. 모든 계산 단계의 영구 저장은 아님 | | 저장 계산 캐시 | 기본 파일 컨테이너 최대 32 MiB. 프로젝트가 참조하는 구조 캐시는 합계 40 MiB 예산 | | 자동 캐시 전송 대기 | 최대 8개 작업, 합계 64 MiB, 24시간 만료. 업로드 전 로컬 쓰기가 실패하면 복구 보장 없음 | | 자동 캐시 압축 해제 검사 | 512 MiB 상한. 파일 크기나 전체 탭 메모리와 다름 | ## 서버 계산의 범위 MCP 서버(`/mcp`)의 계산은 실제 GridEngine으로 Flow를 계산합니다. 앞선 호출이 남긴 계산 상태가 있으면 그 지점부터 이어 계산합니다(아래). 일반 웹 앱의 브라우저 실행과 다른 경로이며, 서버 도구가 연결됐다는 사실만으로 임의 크기의 무제한 헤드리스 계산이 지원되는 것은 아닙니다. 한 번의 계산은 XY 열 약 1,000,000개(`gridResolution`을 반영한 실제 계산 간격 기준)와 실행 단계 400개(Group 반복 펼침 포함)까지 받습니다. 넘으면 `GRID_TOO_LARGE`·`TOO_MANY_STEPS`로 거부하며 해상도나 크기를 자동으로 바꾸지 않습니다. 메모리는 XY 열 수와 각 열의 층 수에 비례해 늘어납니다. 한 번의 계산이 쓸 수 있는 메모리를 넘을 것으로 보이면 다음 단계를 시작하지 않고 `MEMORY_LIMIT`을 돌려줍니다(`details.completedSteps`·`neededMB`·`limitMB`). 계산 상태를 남기지 않으므로 같은 호출을 다시 해도 결과는 같습니다. 영역을 잘라 확인하고 전체 구조는 웹 앱에서 계산하세요. 호출 하나는 약 180초(3분) 동안 계산합니다. 계산이 약 180초를 넘기거나, 지금까지 가장 오래 걸린 단계가 한 번 더 걸리면 약 210초를 넘을 때는 다음 단계를 시작하지 않고, 마친 단계까지의 계산 상태를 서버에 남긴 뒤 `IN_PROGRESS`를 돌려줍니다. `details.completedSteps`는 마친 단계 수, `restoredSteps`는 이번 호출이 앞선 호출에서 이어받은 단계 수입니다. 같은 도구를 같은 인수로 다시 부르면 남은 단계부터 이어 계산하므로, 오래 걸리는 계산도 몇 번에 나눠 끝까지 계산할 수 있습니다. 호출 사이에 `completedSteps`가 늘지 않으면 상태가 남지 않은 것이니 영역을 잘라 확인하거나 앞 단계까지만 계산하세요. 상태를 남길 수 없으면 `IN_PROGRESS` 대신 `TIME_LIMIT`을 돌려주며, 이때 다시 불러도 이어지지 않습니다. 계산 상태는 최대 1시간 남고 그 뒤 자동으로 지워집니다. 상태는 공정 단계로 찾습니다: 어떤 단계까지의 공정(ID·종류·값·쓰는 마스크)과 도메인이 앞선 호출과 같으면 그 지점부터 이어 계산합니다. 그래서 큰 구조를 모듈 하나씩 Flow 끝에 덧붙여 계산하면 매번 새 모듈만 계산하고, 방금 계산한 Flow의 단면·검사·재료 정보는 다시 계산하지 않습니다. 결과(`restoredSteps`)로 확인할 수 있습니다. 앞쪽 공정의 값이나 그 공정이 쓰는 마스크를 바꾸면 그 공정부터 다시 계산합니다. 단계 이름·메모는 상태를 찾는 데 쓰이지 않고 상태에 남지도 않습니다. 이 한도들은 서버 보호를 위한 것이며 브라우저의 안전 크기나 처리 시간 공식이 아닙니다. 한도에 맞추려고 구조의 범위나 실제 치수를 줄이지 마세요. 열·단계 한도 안의 구조는 오래 걸려도 서버에서 끝까지 계산할 수 있습니다. 한도를 넘는 전체 구조는 사용자의 브라우저에서 아펠리에 탭을 조작할 수 있으면 앱에서 계산하고([브라우저에서 모듈별로 만들기](/docs/agents/api.md#브라우저에서-모듈별로-만들기)), 서버 도구는 같은 공정으로 영역만 잘라낸 대표 부분을 검증하는 데 쓰세요. 브라우저가 없으면 전체 Flow와 함께 서버에서 검증한 범위를 밝혀 전달합니다.