============================================================
README – REFLEX (MATLAB Compiled Application for macOS)
============================================================

REFLEX is a MATLAB-compiled application.
MATLAB is NOT required to run this program.

The only requirement is MATLAB Runtime:
MATLAB_Runtime_R2023a_Update_5_maci64.dmg

------------------------------------------------------------
1. Installation of REFLEX
------------------------------------------------------------

1. Download the archive:
   reflex54mac.zip

2. Unzip the archive.

3. Rename the extracted directory to:
   reflex54

4. Place the directory anywhere you want
   (e.g. in your home directory).

------------------------------------------------------------
2. Folder Contents
------------------------------------------------------------

The reflex54 directory contains:

- REFLEX.app        : Main application bundle
- run_REFLEX.sh     : Launch script (recommended)
- data/             : Directory where reflectivity
                       measurements must be placed
- database/         : Physical database REQUIRED for
                       computing optical constants
                       (qc, delta, beta) of compounds
- databaseN/        : Additional REQUIRED database used
                       for material properties and
                       optical calculations
- splash.png        : Splash screen image
- readme.txt        : This documentation file

IMPORTANT:
The directories database/ and databaseN/ are NOT optional.
They are essential for the calculation of qc, delta and
optical properties of different compounds.

------------------------------------------------------------
3. What is MATLAB Runtime?
------------------------------------------------------------

REFLEX was compiled using MATLAB Compiler.
Compiled MATLAB applications require MATLAB Runtime, a free
set of shared libraries provided by MathWorks.

No MATLAB license is required.

IMPORTANT:
The MATLAB Runtime version MUST match the MATLAB version used
for compilation (R2023a).

------------------------------------------------------------
4. Install MATLAB Runtime (macOS)
------------------------------------------------------------

1. Double-click:
   MATLAB_Runtime_R2023a_Update_5_maci64.dmg

2. Double-click:
   "Install MATLAB Runtime"

3. Follow the installation instructions.

NOTE:
The MATLAB Runtime installation may take several minutes.
This is normal. Please be patient and let the installation
complete.

On macOS, MATLAB Runtime is typically installed in:
   /Applications/MATLAB/MATLAB_Runtime/R2023a

------------------------------------------------------------
5. Message About DYLD_LIBRARY_PATH (IMPORTANT)
------------------------------------------------------------

At the end of the installation, MATLAB Runtime displays a
message such as:

"Append the following to your DYLD_LIBRARY_PATH ..."

In NORMAL USE, THIS MESSAGE CAN BE SAFELY IGNORED.

The provided launch script (run_REFLEX.sh) automatically
sets all required environment variables. You do NOT need to
modify DYLD_LIBRARY_PATH manually.

------------------------------------------------------------
Optional: Manual DYLD_LIBRARY_PATH configuration
------------------------------------------------------------

Only for advanced users, or if the launch script is not used,
you may temporarily set DYLD_LIBRARY_PATH in a terminal:

   export DYLD_LIBRARY_PATH=/Applications/MATLAB/MATLAB_Runtime/R2023a/runtime/maci64:\
/Applications/MATLAB/MATLAB_Runtime/R2023a/bin/maci64:\
/Applications/MATLAB/MATLAB_Runtime/R2023a/sys/os/maci64

This setting applies ONLY to the current terminal session.

------------------------------------------------------------
6. macOS Security (Gatekeeper)
------------------------------------------------------------

macOS may block the application because it is not signed by
an identified developer.

If this happens:
- Open System Settings → Privacy & Security
- Click "Allow Anyway"

Alternatively, run in a Terminal:
   sudo xattr -dr com.apple.quarantine /Applications/MATLAB

------------------------------------------------------------
7. Prepare the Application (IMPORTANT)
------------------------------------------------------------

Before running REFLEX for the first time, macOS must be
allowed to execute the launch script.

This is a ONE-TIME operation.

1. Open the Terminal application.
2. Go to the reflex54 directory:
   cd /path/to/reflex54
3. Authorize the launch script by typing:
   chmod +x run_REFLEX.sh

(This command simply tells macOS that the script is allowed
to run. It does not install anything or modify the system.)

------------------------------------------------------------
8. Run REFLEX
------------------------------------------------------------

Recommended method (using the provided script):

   ./run_REFLEX.sh /Applications/MATLAB/MATLAB_Runtime/R2023a

NOTE:
The FIRST TIME REFLEX is launched, startup may take
significantly longer (several tens of seconds).

This is normal and only happens once.
Subsequent launches will start much faster.

------------------------------------------------------------
9. Apple Silicon Macs (M1 / M2 / M3)
------------------------------------------------------------

If REFLEX was compiled for Intel processors, run it using
Rosetta:

   arch -x86_64 ./run_REFLEX.sh /Applications/MATLAB/MATLAB_Runtime/R2023a

macOS will prompt you to install Rosetta if needed.

------------------------------------------------------------
10. Common Issues
------------------------------------------------------------

• Error: "Library not loaded"
  → MATLAB Runtime not installed or incorrect path used.

• Error: "REFLEX.app cannot be opened because the developer
  cannot be verified"
  → macOS security restriction (see section 6).

• Application appears frozen during first launch
  → This is normal. Please wait.

• Application does not start
  → Make sure the launch script has been authorized and the
    runtime path is correct.

------------------------------------------------------------
11. Summary
------------------------------------------------------------

1. Download and unzip reflex54mac.zip into reflex54
2. Install MATLAB Runtime R2023a Update 5 (may take time)
3. Runtime location:
   /Applications/MATLAB/MATLAB_Runtime/R2023a
4. Ignore the DYLD_LIBRARY_PATH message
5. Authorize the launch script (one-time step)
6. First launch may be slow, subsequent launches are fast
7. Launch REFLEX using run_REFLEX.sh