Skip to content

Commit bb88b77

Browse files
author
James Trageser (jtrag)
committed
docs: Core NRC Interactive Visualization Updates
- Added explicit Google Colab execution instructions for remote Math explorations - Hardened High-Dimensional Mathematics and Interactive Simulation SEO parameters - Re-structured OS installation sequences for error-free deployment
1 parent 6fe9c6e commit bb88b77

2 files changed

Lines changed: 246 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 148 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -47,28 +47,154 @@ The NRC is part of an interconnected ecosystem of advanced modeling and research
4747

4848
<br/>
4949

50-
## 🛠️ Installation & Environment
51-
52-
We have established a unified virtual environment mechanism enforcing strict type-checking and native inter-repository execution.
53-
54-
### Global Installation via Pip
55-
56-
To utilize the exact precision computations globally:
57-
58-
```bash
59-
pip install urllib3 numpy mpmath sympy pandas pyarrow huggingface_hub
60-
pip install "nrc @ git+https://github.com/Nexus-Resonance-Codex/NRC.git"
61-
```
62-
63-
### Local Development
64-
65-
To develop identically against the workspace, create a unified environment above the repositories:
66-
67-
```bash
68-
python3 -m venv ../.venv
69-
source ../.venv/bin/activate
70-
pip install -e .
71-
```
50+
## 🛠️ Installation & Cross-Platform Execution (Exhaustive Guide)
51+
52+
The core NRC mathematical engine is built for infinite-precision testing and interactive data visualization. Below are explicitly expanded, foolproof protocols across three dominant operating spheres (Linux, Windows, macOS).
53+
54+
**General Requirements:**
55+
- `python3` (Version 3.10+ recommended)
56+
- `git`
57+
- Access to terminal/command line
58+
59+
### ☁️ Remote Access (Google Colab)
60+
61+
For users lacking the physical compute capabilities required to run these interactive mathematical visualizations natively, Google Colab provides an immediate external environment executing in the cloud.
62+
63+
1. Navigate to **Google Colab** (https://colab.research.google.com).
64+
2. At the top menu, select **File > Open Notebook**.
65+
3. Select the **GitHub** tab.
66+
4. Input the Repository URL: `https://github.com/Nexus-Resonance-Codex/NRC`
67+
5. Click on the file **`interactive_nrc_explorer.ipynb`**.
68+
6. When the notebook opens, you **must prepend** a unique install command to the first cell to load required math operators in Colab. Insert a new block at the beginning containing:
69+
```python
70+
!pip install mpmath sympy matplotlib
71+
```
72+
7. Press `Shift + Enter` to sequentially run and evaluate each interactive mathematical module.
73+
74+
### 🐧 Linux (Pop!_OS / Ubuntu / Debian) - Primary Target
75+
76+
Linux is the premier, biologically analog environment allowing strict control over computational matrices and background physics required by the NRC.
77+
78+
1. **System Core Dependencies Update:**
79+
Open an interactive terminal session and execute sequentially:
80+
```bash
81+
sudo apt update && sudo apt upgrade -y
82+
sudo apt install -y git python3-venv python3-pip python3-dev curl build-essential
83+
```
84+
85+
2. **Install `uv` Configuration Wizard:**
86+
`uv` rapidly constructs virtual environments minimizing package overlap:
87+
```bash
88+
curl -LsSf https://astral.sh/uv/install.sh | sh
89+
# Reactivate session profiles
90+
source $HOME/.bashrc
91+
```
92+
93+
3. **Clone & Mount Repository:**
94+
```bash
95+
git clone https://github.com/Nexus-Resonance-Codex/NRC.git
96+
cd NRC
97+
```
98+
99+
4. **Virtual Environment Isolation:**
100+
```bash
101+
uv venv .venv
102+
source .venv/bin/activate
103+
```
104+
105+
5. **Install The Engine In Editable Mode:**
106+
```bash
107+
uv pip install -e .
108+
```
109+
110+
6. **Deploy Interactive Notebook Server:**
111+
This environment grants you graphical mathematical outputs of the NRC framework:
112+
```bash
113+
uv pip install jupyterlab
114+
# Execute locally
115+
jupyter lab interactive_nrc_explorer.ipynb
116+
```
117+
*(A browser window will automatically launch displaying the geometric constants and scripts.)*
118+
119+
### 🪟 Windows 11 (via WSL2 / Ubuntu)
120+
121+
Avoid utilizing standalone PowerShell or Command Prompt, as path separation structures (backslash \) and C-libraries diverge from standard POSIX compliances, introducing mathematical anomalies. Instead, Windows users must project their processes into the Windows Subsystem for Linux (WSL).
122+
123+
1. **Enable Virtual Windows Subsystem (WSL2):**
124+
Execute from an elevated **Administrator** PowerShell window:
125+
```powershell
126+
wsl --install
127+
```
128+
Reboot your PC to finalize. When Windows returns, an Ubuntu terminal will pop up. Establish a UNIX user/pass (the password won't show visually while typing).
129+
130+
2. **Update Core OS Features within WSL2:**
131+
Inside the Ubuntu window run:
132+
```bash
133+
sudo apt update && sudo apt upgrade -y
134+
sudo apt install -y git python3-venv python3-pip curl build-essential
135+
```
136+
137+
3. **Secure the Mathematics Repository:**
138+
(Ensure you clone this directly into the native Linux filesystem path `~`, not `/mnt/c/`)
139+
```bash
140+
git clone https://github.com/Nexus-Resonance-Codex/NRC.git
141+
cd NRC
142+
```
143+
144+
4. **Create Protective Environment boundaries:**
145+
```bash
146+
python3 -m venv .venv
147+
source .venv/bin/activate
148+
pip install --upgrade pip
149+
```
150+
151+
5. **Install Core & Deploy Jupyter Interactive Server:**
152+
```bash
153+
pip install -e .
154+
pip install jupyterlab
155+
# Deploy
156+
jupyter lab interactive_nrc_explorer.ipynb
157+
```
158+
*(Select the Jupyter link provided in the terminal output, beginning with http://127.0.0.1..., and paste it into Chrome/Edge).*
159+
160+
### 🍏 macOS (Apple Silicon M1/M2/M3 & Intel)
161+
162+
Apple's UNIX underpinning allows the raw mathematical engine to run remarkably fast over its high-memory buses.
163+
164+
1. **Deploy Homebrew Management Script:**
165+
Open Terminal and run:
166+
```bash
167+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
168+
```
169+
*(Append to .zprofile if instructed by the Homebrew installation output).*
170+
171+
2. **Install Exact Python Architecture:**
172+
```bash
173+
brew install python@3.11 git
174+
```
175+
176+
3. **Clone Data Stream:**
177+
```bash
178+
git clone https://github.com/Nexus-Resonance-Codex/NRC.git
179+
cd NRC
180+
```
181+
182+
4. **Establish Venv:**
183+
```bash
184+
python3.11 -m venv .venv
185+
source .venv/bin/activate
186+
pip install --upgrade pip
187+
```
188+
189+
5. **Compile Engine and Run Scripts dynamically:**
190+
```bash
191+
pip install -e .
192+
pip install jupyterlab
193+
194+
# Deploy Interactive Lab
195+
jupyter lab interactive_nrc_explorer.ipynb
196+
```
197+
*(Jupyter Lab will launch in Safari or your default browser automatically).*
72198

73199
<br/>
74200

‎gradio/README.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,101 @@ This Space provides a live, interactive explorer for the mathematical and AI fra
3131
## Source Code
3232

3333
All source code is available in the [NRC GitHub Organization](https://github.com/Nexus-Resonance-Codex).
34+
35+
## 🚀 Running the Interactive Space Locally & Remote Analysis
36+
37+
This suite enables users to natively explore the NRC mathematical constructs through any Web Browser. Follow the explicit procedures corresponding to your OS environment, or use external instances like Google Colab.
38+
39+
### Remote Access (Google Colab / Cloud Notebooks)
40+
41+
If you lack requisite local memory (8GB minimum) or GPU capability, access the `interactive_nrc_explorer.ipynb` file from the cloud:
42+
1. Open Google Colab (colab.research.google.com).
43+
2. Go to **File > Open Notebook > GitHub Tab**.
44+
3. Search for the URL `https://github.com/Nexus-Resonance-Codex/NRC`.
45+
4. Open the `interactive_nrc_explorer.ipynb` file located in the root repository.
46+
5. In the first executable block, prepend this library fetch command: `!pip install gradio mpmath matplotlib`.
47+
6. Use Shift+Enter to run each cell interactively from any Operating System globally.
48+
49+
### 🐧 Linux (Pop!_OS / Ubuntu) - Primary
50+
51+
For native Linux environments, execution overhead is minimized giving mathematically precise speed.
52+
53+
```bash
54+
# 1. Update APT Dependencies and Virtual Managers
55+
sudo apt update && sudo apt install -y git python3-venv python3-pip
56+
57+
# 2. Clone the core repository and orient inward
58+
git clone https://github.com/Nexus-Resonance-Codex/NRC.git
59+
cd NRC/gradio
60+
61+
# 3. Securely separate your environment
62+
python3 -m venv .venv
63+
source .venv/bin/activate
64+
65+
# 4. Integrate required scientific algorithms
66+
pip install --upgrade pip
67+
pip install -r requirements.txt
68+
69+
# 5. Bring the Space Online
70+
python3 app.py
71+
```
72+
73+
### 🪟 Windows 11 (via WSL2 / Ubuntu)
74+
75+
Standalone CMD and PowerShell are discouraged due to directory and module discrepancy. Projection into the WSL environment is mandatory.
76+
77+
```powershell
78+
# 1. Establish the WSL capability in an Administrator PowerShell Console
79+
wsl --install
80+
```
81+
*Wait for installation, reboot your computer, then create a user account in the newly launched Ubuntu console.*
82+
83+
```bash
84+
# 2. Inside the Ubuntu console: Install Linux utilities
85+
sudo apt update && sudo apt install -y git python3-venv python3-pip
86+
87+
# 3. Mount repository directly to inner Linux filesystem (Do not use /mnt/c/)
88+
git clone https://github.com/Nexus-Resonance-Codex/NRC.git
89+
cd NRC/gradio
90+
91+
# 4. Initialize Sandbox and install mathematical libraries
92+
python3 -m venv .venv
93+
source .venv/bin/activate
94+
pip install --upgrade pip
95+
pip install -r requirements.txt
96+
97+
# 5. Launch Service locally
98+
python3 app.py
99+
```
100+
101+
### 🍏 macOS (M-Series Silicon & Intel)
102+
103+
Utilizing Python binaries from package managers like Homebrew guarantees library paths are preserved efficiently across macOS spaces.
104+
105+
```bash
106+
# 1. Install standard tools via Homebrew (https://brew.sh if absent)
107+
brew install python@3.11 git
108+
109+
# 2. Extract repository
110+
git clone https://github.com/Nexus-Resonance-Codex/NRC.git
111+
cd NRC/gradio
112+
113+
# 3. Instantiate the Virtual System
114+
python3.11 -m venv .venv
115+
source .venv/bin/activate
116+
117+
# 4. Finalize Mathematics installations
118+
pip install --upgrade pip
119+
pip install -r requirements.txt
120+
121+
# 5. Execute
122+
python3.11 app.py
123+
```
124+
125+
### Accessing the Web Interface
126+
127+
Upon executing `python3 app.py` (or Python equivalent on your OS), the server terminal will generate a `localhost` URL, typically:
128+
> `http://127.0.0.1:7860/`
129+
130+
**Open this link inside Google Chrome, Safari, or Microsoft Edge** to interact with the Nexus Resonance Codex!
131+

0 commit comments

Comments
 (0)