MPLACE

MicroPlate Layout Arrangement with Constraint Engines

MPLACE is a desktop app with a graphical interface for generating and visualizing microplate layouts. It runs MiniZinc models (e.g., PLAID and COMPD) behind the scenes, so you don't need to write code. Typical use: define compounds/controls, produce plate layouts, and save figures for reports.

Who is this for?

• Biomedical researchers and lab staff who want to:
  • quickly generate microplate layouts from compounds/controls,
  • run a ready-made model (PLAID or COMPD),
  • visualize results without coding.

Main window: generate/load DZN, run model, load/visualize CSV.

Quick Start (about 5–10 minutes)

Follow these steps in order:

Step 1: Install Python

• Windows/macOS: Download and install Python 3.13 or newer from python.org (check "Add Python to PATH" on Windows).

Step 2: Install Python packages

• Open Terminal/Command Prompt and paste:
  • Windows: pip install numpy matplotlib
  • macOS/Linux: python3 -m pip install numpy matplotlib
• If above does not work, you can consult python.org for detailed instructions

Step 3: Install MiniZinc

• Download and install MiniZinc 2.6.4+ from minizinc.org
• Note: PLAID requires the GeCode solver (bundled with MiniZinc).

Step 4: Download MPLACE

• Click "Code → Download ZIP" or clone the repo, then unzip.
• Open the unzipped folder in your file explorer.

Step 5: Configure paths

• Open config/paths.ini in a text editor and verify/edit:
  • minizinc_path = "C:/Program Files/MiniZinc/minizinc.exe" (Windows example)
  • minizinc_path = "/Applications/MiniZincIDE.app/Contents/Resources/minizinc" (macOS example)
  • plaid_path = "mzn/plate-design.mzn" (PLAID main model file, included)
  • plaid_mpc_path = "mzn/plaid_default.mpc"
  • compd_path = "mzn/plate-optimizer.mzn" (COMPD main model file, included)
  • compd_mpc_path = "mzn/compd_default.mpc"

Step 6: Start the app

• In Terminal/Command Prompt from the MPLACE folder:
  • Windows: python mplace.py
  • macOS/Linux: python3 mplace.py

If the window opens, you're ready to go.

Installation (details)

Requirements

• Python 3.12+ (3.13 also tested; 3.11 on macOS may have issues)
• NumPy 2.1+ and Matplotlib 3.10+
• MiniZinc 2.6.4+ (GeCode solver required for PLAID)

Install commands

• Windows:

  pip install numpy matplotlib
  

• macOS/Linux:

  python3 -m pip install numpy matplotlib
  

Known compatibility notes

• If the app behaves oddly on Python 3.11/macOS, try Python 3.12 or 3.13.

Configure (paths.ini explained)

Open config/paths.ini and check or edit the following lines:

• minizinc_path: full path to your MiniZinc executable
• plaid_path: the PLAID model file (included under mzn/, version of 30 September 2025)
• compd_path: the COMPD model file (included under mzn/, version 1.3.4)
• plaid_mpc_path, compd_mpc_path: solver configuration files (included under mzn/)

Example (Windows):

minizinc_path = "C:/Program Files/MiniZinc/minizinc.exe"
plaid_path = "mzn/plate-design.mzn"
compd_path = "mzn/plate-optimizer.mzn"
plaid_mpc_path = "mzn/plaid_default.mpc"
compd_mpc_path = "mzn/compd_default.mpc"

Example (macOS):

minizinc_path = "/Applications/MiniZincIDE.app/Contents/Resources/minizinc"
plaid_path = "mzn/plate-design.mzn"
compd_path = "mzn/plate-optimizer.mzn"
plaid_mpc_path = "mzn/plaid_default.mpc"
compd_mpc_path = "mzn/compd_default.mpc"

Use the App (typical workflow)

1) Generate or load a model file (*.dzn)

• Click "Generate *.dzn file" to define:
  • Desired layout configurations
  • Rows/columns of the plate
  • Compounds and their concentrations
  • Controls and their concentrations
• Alternatively, click "Load *.dzn file" if you already have one.

Tip: You can prepare the compound/control lists with the included Excel file tools/Convert the compounds and controls.xlsx.

Main window: generate/load DZN, run model, load/visualize CSV.

2) Run the model to produce a layout (*.csv)

• Click "Run a model".
• Choose PLAID or COMPD.
• After the model finishes, you'll be asked which CSV format to save:
  • CSV (PharmBio) — the default MPLACE format used for visualization and post-processing
  • CSV (PLATER) — a plate-shaped format compatible with the R plater package (one file per plate). See "Plater format" below.
• Save the resulting CSV file(s) when prompted.

3) Load an existing layout (*.csv) (optional)

• If you already have a layout file, click "Load *.csv file" (MPLACE recognizes both PharmBio and PLATER formats).

4) Visualize the layout

• Click "Visualize *.csv".
• A new window opens with:
  • Plate view tabs (one per layout)
  • A panel showing materials and concentration scales
• Click "Save Layout(s)" to export figures:
  • Single plate: Choose format (PNG or PDF) and save location
  • Multiple plates: Choose to save as individual PNG files or as a single multi-page PDF

What the app produces

• CSV: layout with wells and materials
• PNG/PDF: plate visualizations exported on demand from the visualization window
• Optional: Load a *.dzn file before visualizing to show controls as circles instead of squares

Plater format (export)

MPLACE can export and import layouts to PLATER-compatible CSV files. The PLATER format is a plate-shaped CSV used by the R package plater to read, tidy, and visualize microtiter plates. Key points:

• One file per plate: PLATER expects each CSV to represent a single plate. If your run produces multiple plates, MPLACE will prompt you to save multiple CSVs (one per plate).
• Multiple layouts (variables) can be stored in one file by separating them with a blank row (e.g., Drug, Concentration, Treatment). The plater::read_plate() function converts these into tidy data.
• To read exported PLATER files in R:

library(plater)
df <- read_plate("layout_plater.csv") # single plate
dfs <- read_plates(c("plate1.csv","plate2.csv"), plate_names=c("P1","P2")) # multiple plates

MPLACE can load and visualize both formats. Use PLATER when your downstream analysis or data sharing requires the PLATER ecosystem. Otherwise, you can use the PharmBio format if you want to store information about multiple layouts into one file, as it is more convenient.

Input Tips: Compounds/Controls Format

When generating a *.dzn, compounds and controls are entered as Python-like dictionaries, for example:

• Compounds:

  {'Drug1': [5, '0.1', '0.3'], 'Drug2': [10, '1']}
  

• Controls:

  {'pos': [8, '100'], 'neg': [8, '0'], 'DMSO': [16, '100']}
  

• The number is "replicates"

• Strings are concentrations (numbers or labels)

• Use single quotes as shown

FAQ and Troubleshooting

The app doesn't start

• Ensure Python is installed and accessible from Terminal/Command Prompt (python --version).
• Try python3 instead of python on macOS/Linux.

"MiniZinc not found" or model fails to run

• Check minizinc_path in config/paths.ini
• To locate MiniZinc installation:
  • Windows: Usually C:/Program Files/MiniZinc/minizinc.exe
  • macOS: Try /Applications/MiniZincIDE.app/Contents/Resources/minizinc or /usr/local/bin/minizinc
  • Linux: Try /usr/bin/minizinc or which minizinc in the terminal
• Ensure MiniZinc 2.6.4+ is installed with GeCode solver.

The window opens, but visualization fails

• Check that your CSV has data rows and a header.
• Try re-running the model and saving the CSV again.

Colors repeat with many materials

• The palette supports up to 60 distinct materials. If your layout exceeds this, colors will cycle

Exported PLATER files

• If multiple plates were generated, you will be prompted to save multiple files (one per plate). The completion dialog lists all saved file names.
• If your analysis requires PLATER, prefer exporting in PLATER format; otherwise, use PharmBio.

How do I save figures?

• After visualizing, click "Save Layout(s)" in the visualization window. For multiple plates, choose PNG (individual files) or PDF (single file with all plates).

Advanced

Switching solvers/threads

• Edit mzn/plaid_default.mpc or mzn/compd_default.mpc to change solver settings (see below).

Timeouts

• For COMPD, you may need to increase the timeout from 180s to 300s (or higher) or higher if results are unsatisfactory (see below).

Models

• The repo includes model files under mzn/. You can point paths.ini to other model files if needed.

Solver Configuration (.mpc files)

The .mpc files under mzn/ are plain JSON files that control how MiniZinc runs each model. You can open them in any text editor.

mzn/plaid_default.mpc (PLAID — uses GeCode solver):

{
    "solver": "org.gecode.gecode",
    "parallel": 8,
    ...
}

mzn/compd_default.mpc (COMPD — uses CP-SAT solver):

{
    "solver": "cp-sat",
    "parallel": 8,
    "time-limit": 180000,
    ...
}

Common adjustments:

• Number of threads — change "parallel" to match your machine's CPU count. The default is 8; reduce it if you want to leave cores free for other work:

  "parallel": 4

  or increase if you want to use all available cores on your platform

• Timeout (COMPD only) — "time-limit" is in milliseconds. The default is 180 000 ms (3 minutes). Increase it if COMPD returns a suboptimal layout or times out on large plates without producing a layout, for example:

  "time-limit": 300000

  Note: PLAID does not use a timeout by default, and it runs until a solution is found.

• Switching solvers — change the "solver" field to any solver installed in your MiniZinc distribution. For example, to use CP-SAT for PLAID (if installed):

  "solver": "cp-sat"

  If the configured solver is not found, MPLACE falls back to GeCode with 1 thread and shows a warning on startup.

Roadmap Highlights

• Optional exports to standard formats (e.g., Wellmap TOML)

Citation

The following manuscript in SoftwareX can be used to cite this project:

Gindullin, R., & Francisco Rodríguez, M. A. (2026). MPLACE: MicroPlate layout arrangement with constraint engines. SoftwareX, 34, 102584. https://doi.org/10.1016/j.softx.2026.102584

@article{gindullin2026,
	author = {Gindullin, Ramiz and Francisco Rodr\'iguez, Mar\'ia Andre\'ina},
	title = {MPLACE: MicroPlate layout arrangement with constraint engines},
	year = {2026},
	doi = {10.1016/j.softx.2026.102584},
	URL = {https://doi.org/10.1016/j.softx.2026.102584},
	journal = {SoftwareX},
	volume = {34}
}

Note: The paper describes version 1.2.3. The latest version (1.2.5+) includes additional bug fixes and UX improvements — see the repository for updates.

Credits

MPLACE is developed by Ramiz Gindullin except:

• Several utility functions (used for string format validation and handling of recent files menu bar) were generated by Perplexity AI
• The Tooltips class is taken from squareRoot17

License

MPLACE is under Apache 2.0 LICENSE. The author accepts no responsibility or liability for the use of the project or any direct or indirect damages arising out of its use.