33## Java bridge
44
55MPh is built on top of the Python-to-Java bridge [ JPype] [ jpype ] . It is
6- JPype that allows us to look at [ Comsol's Java API ] [ japi ] and run the
7- same commands from Python. All credit to the JPype developers for making
8- this possible.
9-
10- The Comsol API does not support running more than one client at a time,
11- i.e. within the same Java program. Meanwhile, JPype cannot manage more
12- than one Java virtual machine within the same Python process. If it
13- could, it would be easy to work around Comsol's limitation. (There is
14- an alternative Java bridge, [ pyJNIus] [ jnius ] , which is not limited to
15- one virtual machine, but then fails in another regard: A number of Java
16- methods exposed by Comsol are inexplicably missing from the Python
6+ JPype that allows us to look at Comsol's [ Programming Manual ] [ manual ]
7+ or its [ API reference ] [ api ] and run the same commands from Python. All
8+ credit to the JPype developers for making this possible.
9+
10+ Unfortunately, the Comsol API does not support running more than one
11+ client at a time, i.e. within the same Java program. Meanwhile, JPype
12+ cannot manage more than one Java virtual machine within the same Python
13+ process. If it could, it would be easy to work around Comsol's limitation.
14+ (There is an alternative Java bridge, [ pyJNIus] [ jnius ] , which is not
15+ limited to one virtual machine, but then fails in another regard: A number
16+ of Java methods exposed by Comsol are inexplicably missing from the Python
1717encapsulation.)
1818
1919Therefore, if several simulations are to be run in parallel, distributed
2020over independent processor cores in an effort to achieve maximum speed-up
2121of a parameter sweep, they have to be started as separate Python
22- subprocesses. Refer to section
23- [ "Multiple processes"] ( demonstrations.md#multiple-processes ) for a
24- demonstration.
22+ subprocesses. Refer to section [ "Multiple
23+ processes"] ( demonstrations.md#multiple-processes ) for a demonstration.
2524
2625Additionally, there are some known, but unresolved issues with JPype's
2726shutdown of the Java virtual machine. Notably, pressing <kbd >Ctrl+C</kbd >
@@ -32,29 +31,28 @@ exceptions in application code.
3231
3332## Platform differences
3433
35- The [ Comsol API] [ japi ] offers two distinct ways to run a simulation
36- session on the local machine. One may either start a "stand-alone"
37- client, which does not require a Comsol server. Or one may start a
38- server separately and have a "thin" client connect to it via a
39- loop-back network socket. The first approach is more lightweight and
40- more reliable, as it keeps everything inside the same process. The
41- second approach is slower to start up and relies on the inter-process
42- communication to be robust, but would also work across the network,
43- i.e., for remote sessions where the client runs locally and delegates
44- the heavy lifting to a server running on another machine. If we
45- instantiate the [ ` Client ` ] ( mph.Client ) class without providing a
46- value for the host address and network port, it will create a
47- stand-alone client. Otherwise it will run in client–server mode.
48-
49- On Linux and macOS however, the stand-alone mode does not work out of
34+ The Comsol API offers two distinct ways to run a simulation session on
35+ the local machine. We can either start a "stand-alone" client, which
36+ does not require a Comsol server. Or we first start a server and then
37+ have a "thin" client connect to it via a loop-back network socket. The
38+ first approach is more lightweight and more reliable, as it keeps
39+ everything inside the same process. The second approach is slower to
40+ start up and relies on the inter-process communication to be robust,
41+ but would also work across the network, i.e., for remote sessions where
42+ the client runs locally and delegates the heavy lifting to a server
43+ running on another machine. If we instantiate the [ ` Client ` ] ( mph.Client )
44+ class without providing a value for the network port, it will create a
45+ stand-alone client. Otherwise it will run as a thin client in
46+ client–server mode.
47+
48+ On Linux and macOS, however, the stand-alone mode does not work out of
5049the box. This is due to a limitation of Unix-like operating systems
5150and explained in more detail in [ GitHub issue #8 ] [ issue8 ] . On these
5251platforms, if all you did was install MPh, starting the client in
53- stand-alone mode will raise a ` java.lang.UnsatisfiedLinkError `
54- because required external libraries cannot be found. You would have
55- to add the full paths of shared-library folders to an environment
56- variable named ` LD_LIBRARY_PATH ` on Linux and ` DYLD_LIBRARY_PATH ` on
57- macOS.
52+ stand-alone mode will raise a ` java.lang.UnsatisfiedLinkError ` because
53+ required external libraries cannot be found. You would have to add the
54+ full paths of certain shared-library folders to an environment variable
55+ named ` LD_LIBRARY_PATH ` on Linux and ` DYLD_LIBRARY_PATH ` on macOS.
5856
5957For example, for an installation of Comsol 5.6 on Ubuntu Linux, you
6058would add the following lines at the end of the shell configuration
@@ -69,16 +67,18 @@ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH\
6967```
7068
7169On macOS, the root folder is ` /Applications/COMSOL56/Multiphysics ` .
72- The folder names in this example depend on the installed Comsol version
73- and will have to be adapted accordingly.
74-
75- Requiring this variable to be set correctly limits the possibility of
76- selecting a specific Comsol version from within MPh, as adding multiple
77- installations to that search path will lead to name collisions. One
78- could work around the issue by wrapping a Python program using MPh in
79- a shell script that sets the environment variable only for that one
80- process. Or have the Python program run the Comsol session in another
81- Python subprocess. However, none of this is ideal. Starting the client
70+ The folder names depend on the installed Comsol version and will have
71+ to be adapted accordingly.
72+
73+ Requiring the environment variable to be set correctly limits the
74+ possibility of selecting a specific Comsol version from within MPh,
75+ as adding multiple installations to that search path will lead to name
76+ collisions. One could work around the issue by wrapping a Python program
77+ using MPh in a shell script that sets the environment variable before
78+ starting the Python process. That's effectively what Comsol itself does
79+ to launch its GUI on one of these platforms. Or we could have a Python
80+ program that sets the environment variable and then runs MPh in a second
81+ Python subprocess. Clearly, none of this is ideal. Starting the client
8282should work without any of these detours.
8383
8484The function [ ` mph.start() ` ] ( mph.start ) exists to navigate these
@@ -89,8 +89,7 @@ shell configuration is required up front. This behavior is reflected
8989in the configuration option ` 'session' ` , accessible via
9090[ ` mph.option() ` ] ( mph.config ) , which is set to ` 'platform-dependent' `
9191by default. It could also be set to ` 'stand-alone' ` or ` 'client-server' `
92- before calling [ ` start() ` ] ( mph.start ) in order to override the
93- default behavior.
92+ before calling ` start() ` in order to override the default behavior.
9493
9594Performance in client–server mode is noticeably worse in certain
9695scenarios, not just at start-up. If functions access the Java API
@@ -106,6 +105,7 @@ where this works reliably.
106105
107106
108107[ jpype ] : https://github.com/jpype-project/jpype
109- [ japi ] : https://comsol.com/documentation/COMSOL_ProgrammingReferenceManual.pdf
108+ [ manual ] : https://comsol.com/documentation/COMSOL_ProgrammingReferenceManual.pdf
109+ [ api ] : https://doc.comsol.com/5.6/doc/com.comsol.help.comsol/api
110110[ jnius ] : https://pyjnius.readthedocs.io
111111[ issue8 ] : https://github.com/MPh-py/MPh/issues/8
0 commit comments