Metadata-Version: 2.5
Name: cryspy_editor
Version: 1.17.1
Summary: Graphical editor for CrysPy: rcif files, refinement and MEM
Project-URL: Homepage, https://github.com/ikibalin/cryspy_editor
Project-URL: Source Code, https://github.com/ikibalin/cryspy_editor
Project-URL: Issue Tracker, https://github.com/ikibalin/cryspy_editor/issues
Project-URL: CrysPy, https://github.com/ikibalin/cryspy
Author-email: Iurii Kibalin <yurikibalin@outlook.com>
License-Expression: MIT
License-File: LICENSE
Keywords: CrysPy,MEM,RhoChi,neutron diffraction,rcif
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: cryspy[all]>=0.20.0
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pyqt5>=5.15
Requires-Dist: pyqtwebengine>=5.15
Provides-Extra: ai
Requires-Dist: llama-cpp-python; extra == 'ai'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: versioningit; extra == 'dev'
Description-Content-Type: text/markdown

# cryspy_editor
 Editor for CrysPy library

Download page: https://ikibalin.github.io/cryspy_editor/

## Start

```
cryspy-editor                  # opens the last used file
cryspy-editor path/file.rcif   # opens the given file
python -m cryspy_editor path/file.rcif
```

Other programs (for example PyColl5) can open a file in CrysPy Editor the
same way. Recent files are in **File → Open recent**.

Settings are kept in `settings.json` in the user's folder:
`%APPDATA%\CrysPyEditor` on Windows, `~/Library/Application Support/CrysPyEditor`
on macOS, `~/.config/cryspy_editor` on Linux. Settings of older versions are
moved there at the first start.

At startup CrysPy Editor asks GitHub (in the background, silently when
offline) whether a newer release exists and then shows a window with a link
to the [download page](https://ikibalin.github.io/cryspy_editor/) (and the
`pip install --upgrade cryspy_editor` command for pip installations). The
check is switched off by **Options → Check for new versions at startup**;
**Options → Check for new version now** checks by hand.

## Standalone program (no Python needed)

Each release has ready programs in **Assets** on the
[Releases page](https://github.com/ikibalin/cryspy_editor/releases):
Python, CrysPy, Qt and llama-cpp-python are inside, nothing else to install.

- **Windows**: `CrysPy-Editor-<version>-Windows-x64.zip`. Unpack it and run
  `CrysPy Editor.exe` in the unpacked folder. On the first start
  Windows SmartScreen may say "unknown publisher": **More info → Run anyway**.
- **macOS** (Apple Silicon): `CrysPy-Editor-<version>-macOS-arm64.dmg`. Drag
  **CrysPy Editor** to Applications. The program is not signed by Apple, so on
  the first start use right click → **Open** → **Open** (or
  System Settings → Privacy & Security → **Open Anyway**).
- **Linux** (x86-64, glibc 2.35 or newer):
  `CrysPy-Editor-<version>-Linux-x64.tar.gz`. Unpack it and run
  `"CrysPy Editor/CrysPy Editor"`.

GGUF models are not inside: choose a downloaded `.gguf` file in
**AI assistant → Load model (GGUF file or Ollama)...**.

## 3D view of crystal structures

Select a crystal block: the **3D view** tab shows its structure (atoms of the
chosen number of unit cells, bonds, cell, axes and magnetic moments from
`atom_site_moment` / mcif). Rotate with the left mouse button, zoom with the
wheel. The settings panel on the right is made from
`cryspy.StructureViewSettings`, the page itself by CrysPy (py3Dmol).
3Dmol.js is bundled (`cryspy_editor/widgets/js`), so no internet is needed.

## AI assistant (optional)

CrysPy Editor can use a local language model to answer questions and work
on the opened file. The model runs on your computer; nothing is sent to the
internet. It calls the tools of CrysPy (`cryspy.assistant_tools()`): help
lookup, list / refine / fix / set parameters by their paths, calculate,
refine, show the model, add an atom, run CrysPy procedures and call the
methods of the data blocks, loops and items of the file (e.g.
`define_background_points` of a powder experiment: "define the background
points"; the methods and their arguments come from CrysPy, `list_methods`,
`call_method`). Questions such as
"how to describe multipoles?" or "what should be used for thermal
vibrations?" are answered from the help pages of CrysPy, which are shown in
the answer. The same help is in **Options → CrysPy help...** (F1) without a
model.

The assistant works in its own window, **AI Assistant / CrysPy Editor**,
opened by **AI assistant → Show assistant**. One request may hold several
actions (e.g. "fix everything, refine the cell and run the refinement"); a
call with wrong arguments goes back to the model to be corrected, and
questions are answered from the results of the actions. The request field
has several lines and grows with the text: Enter sends the request,
Shift+Enter starts a new line. The window and the
logic are the same as in the assistant of PyColl5; only the actions differ.

1. Install the optional dependency: `pip install cryspy_editor[ai]`
   (or `pip install llama-cpp-python`). It is needed only for a GGUF file;
   with Ollama or another server (see below) skip this step.

   PyPI has no ready wheel of llama-cpp-python, so pip compiles it during the
   installation. Install a C/C++ compiler first:
   - **Windows**: [Build Tools for Visual Studio](https://visualstudio.microsoft.com/visual-cpp-build-tools/),
     workload "Desktop development with C++" (MSVC and the Windows SDK);
     then open a new terminal and run `pip install cryspy_editor[ai]`;
   - **macOS**: `xcode-select --install`;
   - **Linux**: `gcc`, `g++` and `make` from the package manager
     (e.g. `sudo apt install build-essential`).

   The compilation takes several minutes. An error such as
   `CMAKE_C_COMPILER not set` or `'nmake' ... no such file or directory`
   means that no compiler was found: install it as above and repeat. If a
   compiler cannot be installed, use Ollama instead (nothing to compile).
2. Download once any instruct (chat) model in GGUF format, Q4_K_M
   quantization. The file should take no more than half of the memory:

   | Memory | Model | Q4_K_M file |
   | --- | --- | --- |
   | < 8 GB | Qwen2.5-3B-Instruct (single requests only: too weak for recipes) | 2 GB |
   | 8 GB | Qwen2.5-7B-Instruct, or the thinking Qwen3-8B (better plans, slower) | 4.7–5 GB |
   | 16 GB and more | Qwen3-14B (thinking), or Qwen2.5-14B-Instruct | 9 GB |
   | 32 GB and more | Qwen3-30B-A3B (thinking; mixture of experts: as fast as an 8B model) | 18 GB |

   Recommended: Qwen2.5-7B-Instruct Q4_K_M; with 16 GB of memory or more
   Qwen2.5-14B-Instruct Q4_K_M, which follows the step-by-step recipes much
   more reliably. Take a general *Instruct* model, not a *Coder* one, and the
   Q4_K_M quantization (more accurate than Q4_0 at the same size). For the
   step-by-step work by recipes set the context to 8192 or more. A
   *thinking* model (Qwen3, e.g. *Qwen/Qwen3-14B-GGUF*; in Ollama
   `qwen3:14b`) thinks before each answer: it plans the steps and reads a
   request better, but answers more slowly; switch on **Thinking** and set
   the context to 16384 or more.

3. In CrysPy Editor choose **AI assistant → Load model (GGUF file or Ollama)...**,
   pick the file and, if needed, the threads, GPU layers, context size,
   answer length and temperature. The same table is shown there, with the row
   for your computer in bold. When the file is chosen, the context range of the
   model (from its GGUF header) and the context recommended for the memory of
   your computer are shown under the field, and the field is set to it. The model is loaded in the background and is
   loaded again at the next start, until **Unload model**; the window opens
   again at the next start if it was open when the program was closed.

**Ollama or another server.** Instead of a GGUF file the assistant can use a
model of [Ollama](https://ollama.com) (e.g. after `ollama pull qwen2.5:7b-instruct`)
or of an OpenAI-compatible server (LM Studio, llama.cpp server, vLLM): choose it
in **Source**, give the address of the server and pick the model (**List models**).
Everything else works the same; llama-cpp-python is not needed then.

**Thinking models.** A thinking model (qwen3, deepseek-r1, ...) can think
before each answer: turn on **Thinking** in the model settings (it is offered
only for a model that can think). Its thinking is shown in the assistant window
apart from the answers (button **Thoughts**), as it goes, and is cleared at each
new request. **Maximal thinking length** limits it: the model is asked to think
briefly, and a longer thinking is stopped, after which the model decides from
what it has thought without thinking again (Ollama and GGUF files; another
server is only asked to be brief). The thinking is a part of the answer, so the
**Maximal answer length** must hold it: the value recommended for the model,
the thinking limit and the context is set and explained under the field.

**Recipes.** A task of several steps (e.g. "refine the structure step by
step", "refine the flip ratios") is done by a recipe of CrysPy: the model
reads its steps and works one action at a time, judging each result by
chi_sq/n, R_F2 and the warnings of CrysPy. Each step is written in the chat
as it starts and when its result comes; **Stop** ends the work, and at most
"Maximal number of steps of the agent" actions (12 by default, in the model
settings) are done for one request. A request without a recipe goes on in
the same way when the first answer of the model only says what it will do
next ("I will check the attributes and add the multipoles"). The recipes
for the experiments of the opened file (single crystal, powder, flip ratios,
nuclear or magnetic crystal) are given to the model. **AI assistant →
CookBook...** lists the recipes, shows their text and lets you write new ones
or change those of CrysPy (New, Check, Save, Delete); your recipes are kept in
the `recipes` folder next to the settings and replace the recipes of CrysPy
with the same name.

**Writing a recipe with the assistant.** Describe the algorithm in words
("write a recipe: fix all, refine the scale, then the atomic positions and
undo a step when R_F2 gets worse") and the assistant writes the recipe for
the CookBook: it reads the format, asks you what is not clear (Q1, Q2, ...,
answered in the chat; `cancel` stops), checks the text with CrysPy, shows it
and saves it to your recipes when you agree (it asks before replacing a
recipe of yours). Nothing in the opened file is changed meanwhile. A thinking
model (turn on **Thinking**) works out such an algorithm better; give it a
context of 8192 tokens or more. The assistant may ask you in the middle of
other step-by-step work too, and goes on from your answers.

**Recipes from recipes.** A step of a recipe may do a whole recipe of the
CookBook: `Actions: use_recipe {"name": "refine_background"}`. So small
recipes are bricks of bigger ones, and those of still bigger ones; the
assistant does the steps of the inner recipe and goes on with the next step
(without a model `run_recipe` does the same). CrysPy rejects a recipe that
uses an unknown recipe or recipes that use each other in a circle.

**Commands.** Type `@` in the input line to see the names of the recipes and
of the actions with a short description (Tab and Shift+Tab go through them,
Enter takes one), and run one directly, without the
model choosing it: `@refine_flip_ratio_nuclear`, `@refine_parameters scale`,
`@set_parameter path=cell.length_a value=5.43` or with a JSON object of the
arguments. Without a loaded model a recipe is done as it is written, step by
step. "What can you do?" (or `help`, `?`) lists the recipes and the actions.

## Development

- `main` holds releases, `develop` is the integration branch. Branch off
  `develop` and open pull requests into `develop`.
- Every pull request needs one label: `[scope] bug`, `[scope] enhancement`,
  `[scope] documentation`, `[scope] maintenance` or `[scope] significant`.
  The label decides the next version in the release draft.
- The version comes from git tags (plain, e.g. `1.9.10`) via versioningit.
- Download page: `site/index.html`, published on GitHub Pages by
  `.github/workflows/pages.yml` when it changes on `main` (or by hand in
  Actions). It reads the latest release from the GitHub API in the browser.
- Tests: `pip install -e .[dev]`, then `python -m pytest`. Qt runs without a
  display in tests (`QT_QPA_PLATFORM=offscreen`).
- Standalone programs: `.github/workflows/build-apps.yml` builds them with
  PyInstaller (`packaging/cryspy_editor.spec`) on Windows, macOS and Linux
  when a release is published and attaches them to the release; only the
  3 newest releases keep these archives. It can also be started by hand in
  Actions. Locally: `pip install .[ai] pyinstaller`,
  then `pyinstaller packaging/cryspy_editor.spec`; the program is in `dist/`.
  `cryspy-editor --self-test` checks a built program.
