# PrimeXP 

## The "Glass Box" Philosophy"
PrimeXP is built on the principle of transparency. It is designed to be an
auditable, rigorous tool for answering scientific problems, expressly
rejecting the "black box" obfuscation common in modern software. 

## Installation and Launch Instructions

PrimeXP is intended to be a cross-platform tool. The core application logic
and mathematical engine reside entirely within the src directory.

### Command Line Usage (macOS / Linux / Windows)
The original intention was to run PrimeXP directly directly via a terminal. 

1. Ensure you have a modern version of Python 3 installed on your system.
   PrimeXP was developed using Python 3.12.9.
2. Open your terminal or command prompt.
3. Navigate into the source directory:
   cd path/to/src            <--- change as necessary
4. Install any necessary dependencies (if applicable), i.e., PyQt6, PyOpenGL, 
    NumPy, scikit-image, SciPy, and NetworkX.
5. Execute the main Python script to launch the application:
   python -B PrimeXP.py      <--- or python3 -B PrimeXP.py
   Note: The -B flag suppresses generation of .pyc files, and has virtually 
   no effect on program launch times.

### macOS Standalone Application
For 'Apple silicon' Macs, a clickable app, which contains only the Python
interpreter and external libraries, is available. For Mac users utilizing this
bundled PrimeXP.app wrapper, macOS Gatekeeper might initially block it from
running to protect your system from unidentified developers. To launch the
standalone app for the first time:

1. Ensure the PrimeXP.app file and the src folder are placed in the same
   directory (side-by-side).
2. DO NOT double-click the PrimeXP application icon.
3. Instead, Right-Click (or Control-Click) the PrimeXP.app icon.
4. Select "Open" from the context menu.
5. A warning dialog will appear stating that the developer cannot be verified.
   Click the "Open" button in this dialog.

*You only need to do this Right-Click process once. For all future uses, you
can simply double-click the PrimeXP app icon to launch the program normally.*

#### Web Download Troubleshooting (Quarantine Flag)
If you downloaded the compressed PrimeXP application via a web browser (e.g.,
Safari), macOS automatically attaches a "quarantine" flag to the file. When
extracted, this causes macOS to silently mount the app in a randomized, read 
only location (App Translocation). Because the app relies on relative paths to 
locate external modules and the accompanying src folder, this randomization 
prevents the program from launching.

To resolve this, you must clear the quarantine flag using the terminal:
1. Open your terminal.
2. Run the following command, modifying the path to point to your unzipped app:
   xattr -cr /path/to/PrimeXP.app

Once the flag is cleared, you can follow the Right-Click instructions above
to open the app.

> Note: Whether running via the terminal or the macOS app, the src folder
contains the core application code and must remain intact and accessible to
the program at all times. The src directory can be updated to get the latest
version of PrimeXP, without changing the clickable app, so long as the
PrimeXP.app file and the src folder are placed in the same directory.

## User Configuration
PrimeXP allows users to customize the application via a .PrimeXP.cfg
preferences file. The application automatically searches for this file in
standard, OS-specific directories during startup.

### macOS and Linux
Place your configuration file in the following user config directory:
~/.config/PrimeXP/.PrimeXP.cfg

*(Note: The legacy location directly in the home directory at ~/.PrimeXP.cfg
is also supported as a fallback).*

### Windows
For Windows users, the configuration file should be placed in the native 
AppData Roaming directory:
%APPDATA%\PrimeXP\.PrimeXP.cfg

Because the AppData folder is hidden by default in Windows, follow these steps
to access this location and set up your configuration:
1. Open the Windows File Explorer.
2. Click directly on the address bar at the top of the window.
3. Type %APPDATA% and press Enter. (This will bypass the hidden folder
   restrictions and open your Roaming folder).
4. Create a new folder there named PrimeXP.
5. Place your .PrimeXP.cfg file inside this new folder.

## Licensing and Governance
PrimeXP is released under the GNU General Public License v3 (see LICENSE.txt).
It is free software; you can redistribute it and/or modify it under the terms
of the GPL v3.

* Official Upstream: Sean R. Parkin is the Lead Architect and holds final
  authority on all merges to the official branch. 
* Forks and Modifications: Per GPL v3 Section 6, any distributed modified
  versions or forks MUST be clearly marked and renamed so as not to be
  confused with the official PrimeXP release.
* Commercial / Non-GPL Licensing: For commercial entities whose distribution
  models are incompatible with the GPL v3, alternative licensing (including
  in-kind cooperation agreements) is available. Please contact the Lead
  Architect (Parkin) directly.

## Development Methodology and Authorship
PrimeXP was designed and developed by Sean R. Parkin. The architecture,
crystallographic logic, and scientific constraints are home grown. 

The development process used a Large Language Model (LLM) as an advanced 
coding tool. While the LLM was responsible for generating some raw Python, 
executing requested refactors, and assisting with routine scripting, it 
operated strictly under human supervision. Every line of code has been tested, 
verified, and iteratively modified to ensure absolute crystallographic rigor, 
mathematical accuracy, and structural integrity. 

The LLM functioned as a sophisticated syntax engine; the scientific method,
application design, problem-solving logic, and domain expertise driving the
software belong entirely to the author. 

Bugs are undoubtedly still present, so please let me know if something does
not seem right.