============================================================================= OCTA85 for macOS Apr.24, 2025 ============================================================================= Contents: [0] Introduction [1] Install [2] Notes for users upgrading from OCTA84 [3] Starting Gourmet [4] Running simulation engines - Multiprocessing by OpenMP (cognac/kapsel) [5] Using bundled Python with UDFManager etc. [Appendix 1] Using tools other than Gourmet [Appendix 2] How to rebuild Gourmet and/or simulation engines [Appendix 3] Other notes - How to use Mouse in Gourmet - Using Apple's Look and Feel ================ [0] Introduction ================ This is a binary distribution of OCTA85 for macOS (unofficial release). Supported macOS: Big Sur (11.0) or later (x86_64 and arm64). --------------- This distribution includes pre-built binaries of Gourmet and simulation engines (and source code of them) Python3.11 JRE-17 (Java runtime), and should work "out-of-the-box" (hopefully). (You need to install gnuplot by yourself, though.) Please report any problems to OCTA-BBS. -------------------------------------- =========== [1] Install =========== (1) Download either OCTA85-mac-x86_64.tar.xz for Intel Mac, or OCTA85-mac-arm64.tar.xz for Apple Silicon (2) IMPORTANT --------- Open a Terminal window, and (% is the prompt of your shell) % xattr -c ~/Downloads/OCTA85-mac-ARCH.tar.xz (ARCH = x86_64 or arm64) # We assume you have downloaded the .tar.xz into your Downloads # directory. If the .tar.xz is in other directory, please replace # the '~/Downloads' by appropriate path. (3) Expand the tar.xz into anywhere you like. For example, if you want to install under your home directory, % cd # cd to your $HOME % tar xvf ~/Downloads/OCTA85-mac-ARCH.tar.xz That's all!. (Please read the license documents in OCTA85/DOCUMENTS/) (4) Install gnuplot Gourmet can start without gnuplot (see [3] below), but requires gnuplot for creating plots. As of writing, you can download macOS binary of gnuplot from: https://csml-wiki.northwestern.edu/index.php/Binary_versions_of_Gnuplot_for_macOS Or you can install gnuplot by using homebrew, MacPorts, etc. (5) Create Gourmet.app (optional, but highly recommended) You need to create Gourmet.app by yourself, but it is _very_ easy and we strongly recommend creating one. Step-by-step instructions for creating Gourmet.app are in: OCTA85/DOCUMENTS/How-to-Create-Gourmet.app.pdf. Once you have created Gourmet.app, you may: Add Gourmet.app to the Dock. Then you can click it to start Gourmet, or drag and drop UDF files to it to open them by Gourmet. Set Gourmet.app as the default app for UDF files. Then you can double click a UDF file in Finder to open it by Gourmet. ========================================= [2] Notes for users upgrading from OCTA84 ========================================= (0) You need not uninstall OCTA84 (1) The Gourmet startup script "gourmet" is moved from GOURMET/gourmet to GOURMET/bin/gourmet. (2) There were two scripts for setting environment variables for OCTA84: OCTA84/GOURMET/gourmetterm, OCTA84/GOURMET/engine_env These are replaced by OCTA85/octa_env. If you have a line like source /path/to/OCTA84/GOURMET/engine_env or source /path/to/OCTA84/GOURMET/gourmetterm - in your .zshrc or .bashrc, please replace it by source /path/to/OCTA85/octa_env ==================== [3] Starting Gourmet ==================== You can start Gourmet by the script "gourmet" in GOURMET/bin: % /path/to/OCTA85/GOURMET/bin/gourmet (/path/to/ is the directory under which you have installed OCTA85) Please do NOT move/copy this script. But you can either create a symlink to this script in your PATH, or create an alias % alias gourmet=/path/to/OCTA85/GOURMET/bin/gourmet Then: % gourmet # open an empty Editor or % gourmet xxx.udf yyy.udf # start two Gourmet Editors NOTE: If you source octa_env into your shell (see [4] below), /path/to/OCTA85/GOURMET/bin is added to your PATH, and you need not create a symlink or alias. Of cause, if you have created Gourmet.app in [1](5) above, you can start Gourmet by using the app. ============================== [4] Running simulation engines ============================== In order to run simulation engines, you need to set several environment variables (including PATH). You can set them by % source /path/to/OCTA85/octa_env Then, for example % cognac112 -I xxx_in.udf -O xxx_out.udf Multiprocessing by OpenMP (cognac and kapsel) --------------------------------------------- Cognac: use the -n option to specify the number of threads: % cognac112 -n 4 -I xxx_in.udf -O xxx_out.udf If -n is not specified, only one CPU core is used. Kapsel: set environment variable OMP_NUM_THREADS: % export OMP_NUM_THREADS=4 % kapsel -Iinput.df -Ooutput.udf -Ddefine.udf -Rrestart.udf If OMP_NUM_THREADS is not defined, maximum number of cores will be used (this may not be optimal). =================================================== [5] Using bundled Python3.11 (with UDFManager etc.) =================================================== If you want to use the OCTA's Python modules (such as UDFManager), you need to use the bundled Python3.11. First, please source octa_env: % source /path/to/OCTA85/octa_env Then make sure that you are using the bundled Python3.11: % which python3 /path/to/OCTA85/Python3.11/bin/python3 Now % python3 >>> from UDFManager import UDFManager >>> udf = UDFManager('xxx_out.udf') ... =========================================== [Appendix 1] Using tools other than Gourmet =========================================== Startup scrips for AITool, FillingParticleTool, ImageLoader, and PatternMatchingStructureGenerator are in OCTA85/GOURMET/bin/. FillingParticleTool requires no Python modules. AITool, ImageLoader or PatternMatchingStructureGenerator require additional Python modules. See OCTA85/Python3.11/README-Python.txt for how to install them. ============================================================= [Appendix 2] How to rebuild Gourmet and/or simulation engines ============================================================= (0) If you don't have Xcode.app, install Apple's command line tool: % xcode-select --install (1) rebuild simulation engines First, you need to source OCTA85/octa_env (see [4]). Then you can rebuild each engine by going to the src directory of the engine, and running 'make; make install'. For example: % cd /path/to/OCTA85 % source ./octa_env % cd ENGINES/COGNAC1124/src % make -j 4 # 4 is the number of processes used for the build % make install If you want to rebuild all the engines: % cd /path/to/OCTA85/ENGINES % ./build-engines You can remove intermediate files by % ./build-engines -c If the engines still do not work, you may need to rebuild libplatform (UDF I/O library used by engines) by: % cd /path/to/GOURMET/src % ./build-lib and try rebuilding engines again. (2) rebuild Gourmet You need to install OpenJDK (11, 17 or 21). OpenJDK from any source would work. We are using Eclipse Temurin: https://adoptium.net/temurin/releases/ Then: % cd /path/to/OCTA85/GOURMET/src % ./build-gourmet -r 17 (replace 17 by your OpenJDK's version) This will use the bundled Python3.11. If you want to use your own Python (3.11 or older), % ./build-gourmet -r 17 -p /path/to/your/python3 You can remove intermediate files by % ./clean-all If you have any problems, please ask in OCTA-BBS. ======================== [Appendix 3] Other notes ======================== How to use Mouse in Gourmet --------------------------- Editor window: Data name in the 'Name' column that are in boldface font have action menu. To open it, cmd-click (or right-click) the data name. Viewer window: left-drag: rotate option-drag/right-drag: zoom shift-drag: translate ctrl-click: action menu Using Apple's Look and Feel --------------------------- Gourmet now uses the Metal Look and Feel (LAF) by default (this is the LAF used by Windows/Linux versions of Gourmet). If you prefer Apple's LAF, please use the option -a: % gourmet -a xxx.udf With Apple's LAF, you need to double click the folder-like icon to open the data structure in the Tree View of Gourmet Editor. =============================================================================